Allgemeine Referenz

Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.

Elementare Typen

type TtakInt64

Ein vorzeichenbehafteter Ganzzahltyp mit insgesamt 64 Bit. Belegt 8 Bytes.

type TtakInt32

Ein vorzeichenbehafteter Ganzzahltyp mit insgesamt 32 Bit. Belegt 4 Bytes.

type TtakUInt32

Ein vorzeichenloser Ganzzahltyp mit insgesamt 32 Bit. Belegt 4 Bytes.

type TtakBool

kann nur zwei Werte annehmen:

tak_False

Falsch bzw. Nein.

tak_True

Richtig bzw. Ja.

Funktionsergebnisse und Fehler

type TtakResult

Funktionsergebnis und Objektstatus.

Pascal:

type
  TtakResult = TtakInt32;

C:

typedef TtakInt32 TtakResult;

const tak_res_xxx

Allgemeine Ergebniskonstanten. Jedes Objekt kann zusätzliche spezifische Ergebnisse definieren.

Erfolg:

tak_res_Ok

Ok.

Systemfehler:

tak_res_InternalError

TAK's Fehler...

tak_res_NotImplemented

Diese Funktion ist noch nicht implementiert.

tak_res_IncompatibleVersion

Diese Funktion wird von der verwendeten Bibliotheksversion nicht unterstützt. Z.B. ein neuer Codec.

tak_res_OutOfMemory

Eine Speicheranforderung konnte nicht erfüllt werden.

Anwenderfehler:

tak_res_InvalidParameter

Ungültiger Funktionsparameter, z.B. Bereichsüberschreitung oder Null-Referenz.

tak_res_InvalidIoInterface

Ein TtakStreamIoInterface liefert nicht die benötigte Funktionalität.

tak_res_InvalidMode

Das Objekt befand sich in einem Modus, der die Ausführung der gewünschten Funktion nicht erlaubt.

tak_res_BufferTooSmall

Ein als Parameter übergebener Puffer (z.B. für Zeichenketten) war zu klein.

tak_res_NotEnoughAudioData

Der Encoder sollte geschlossen werden, obwohl weniger Audiodaten geschrieben wurden, als bei der Initialisierung angegeben.

tak_res_TooMuchAudioData

Der Encoder sollte mehr Audiodaten schreiben, als bei der Initialisierung angegeben.

Bibliothek

const tak_InterfaceVersion

Die Version der Bibliotheksschnitstelle. Durch einen Vergleich mit den Versionsinformationen, die tak_GetLibraryVersion liefert, kann die Kompatibilität mit der verwendeten Bibliotheks-DLL geprüft werden:

tak_InterfaceVersion muß <= AVersion und >= ACompatibility sein.

function tak_GetLibraryVersion

Liefert Versionsinformationen der Bibliothek.

Pascal:

function tak_GetLibraryVersion (var AVersion       : TtakInt32;
                                var ACompatibility : TtakInt32) : TtakResult; cdecl;

C:

TtakResult tak_GetLibraryVersion (TtakInt32 * AVersion,
                                  TtakInt32 * ACompatibility);

AVersion enthält die dreistellige Versionsnummer der Bibliothek. Jede Stelle ist ein Byte groß, die niedrigste Stelle steht im niedrigsten Byte.

Beispiel: 00010000h = 1.0.0

ACompatibility enthält die Versionsnummer der ältesten Bibliothek, zu der diese Version abwärtskompatibel ist.

Das Ergebnis ist immer tak_res_Ok, wenn die Parameter gültig sind.

System

type TtakCpuOptions

Spezifiziert CPU Features für Optimierungen.

Pascal:

type
  TtakCpuOptions = TtakInt32;

C:

typedef TtakInt32 TtakCpuOptions;

Folgenden Flags können eingesetzt und ggfs. per bitweisem Oder kombiniert werden:

tak_Cpu_Asm

Verwende Assembler-Optimierungen, die keinerlei CPU-spezifische Befehle nutzen. Wird derzeit ignoriert.

tak_Cpu_MMX

Verwende MMX (64-Bit).

tak_Cpu_SSE

Verwende SSE1. Ist derzeit nicht implementiert.

tak_Cpu_None

Verwende keinerlei Code-Optimierungen.

tak_Cpu_Any

Verwende alle vom Zielsystem unterstützten Code-Optimierungen.

TAK deaktiviert automatisch Optionen, die von der CPU nicht unterstützt werden.

type TtakStreamIoInterface

Interface für externe Implementierungen der Dateizugriffe.

Pascal:

type
  PtakStreamIoInterface = ^TtakStreamIoInterface;
  TtakStreamIoInterface = packed record
    CanRead   : function (AUser : Pointer) : TtakBool; cdecl;
    CanWrite  : function (AUser : Pointer) : TtakBool; cdecl;
    CanSeek   : function (AUser : Pointer) : TtakBool; cdecl;
    Read      : function (    AUser    : Pointer;
                              ABuf     : Pointer;
                              ANum     : TtakInt32;
                          var AReadNum : TtakInt32) : TtakBool; cdecl;
    Write     : function (AUser : Pointer;
                          ABuf  : Pointer;
                          ANum  : TtakInt32) : TtakBool; cdecl;
    Flush     : function (AUser : Pointer) : TtakBool; cdecl;
    Truncate  : function (AUser : Pointer) : TtakBool; cdecl;
    Seek      : function (AUser : Pointer;
                          APos  : TtakInt64) : TtakBool; cdecl;
    GetLength : function (    AUser   : Pointer;
                          var ALength : TtakInt64) : TtakBool; cdecl;
  end;

C:

typedef struct TtakStreamIoInterface {
    TtakBool (*CanRead)  (void * AUser);
    TtakBool (*CanWrite) (void * AUser);
    TtakBool (*CanSeek)  (void * AUser);
    TtakBool (*Read)     (void *      AUser,
                          void *      ABuf,
                          TtakInt32   ANum,
                          TtakInt32 * AReadNum );
    TtakBool (*Write)    (void *       AUser,
                          const void * ABuf,
                          TtakInt32    ANum);
    TtakBool (*Flush)    (void * AUser);
    TtakBool (*Truncate) (void * AUser);
    TtakBool (*Seek)     (void *    AUser,
                          TtakInt64 APos);
    TtakBool (*GetLength)(void *      AUser,
                          TtakInt64 * ALength);
} TtakStreamIoInterface;
typedef TtakStreamIoInterface* PtakStreamIoInterface;

Funktionen:

CanRead

CanWrite

CanSeek

Kann gelesen, geschrieben und gesucht werden?

Read

Lese maximal ANum Bytes nach ABuf. AReadNum enthält die Zahl tatsächlich gelesener Bytes.

ACHTUNG: Derzeit darf AReadNum nur am Dateiende kleiner als ANum sein!

Write

Schreibe ANum Bytes aus ABuf in die Datei. Weniger geht nicht. Deshalb muß der Anwender ggfs. selbst puffern.

Flush

Schreibe ggfs. alle Pufferinhalte in die Datei. Wird von TAK in der Regel nur einmal am Dateiende aufgerufen.

Truncate

Lösche alles ab einschließlich der aktuellen Dateiposition. Die Datei wird also gekürzt. Wird wahrscheinlich für Updates von ApeV2-Tags gebraucht.

Seek

Setze den Dateizeiger auf die absolute Position APos.

GetLength

Liefere in ALength die Dateigröße in Bytes.

ACHTUNG: Die Dateigröße darf sich derzeit bei wiederholten Aufrufen niemals ändern, es sei denn entsprechend den Schreiboperationen, die TAK angefordert hat!

Als ersten Parameter erhält jede Funktion Anwenderdaten in Form des Zeigers AUser, der bei der Übergabe des Interfaces an ein TAK-Objekt spezifiziert wurde.

Fehler werden, sofern nicht anders angegeben, durch das Funktionsergebnis tak_False angezeigt. Jeder Fehler wird von TAK als fatal angesehen und beendet die Dateiverarbeitung.

Audio-Format

const tak_AudioFormat_xxx

Spezifikation des Audiodatenformates:

tak_AudioFormat_DataType_PCM

PCM-Audio.

type TtakAudioFormat

Spezifikation des Audioformates.

Pascal:

type
  TtakAudioFormat = packed record
    DataType   : TtakInt32;
    SampleRate : TtakInt32;
    SampleBits : TtakInt32;
    ChannelNum : TtakInt32;
    BlockSize  : TtakInt32;
  end;

C:

typedef struct TtakAudioFormat {
    TtakInt32 DataType;
    TtakInt32 SampleRate;
    TtakInt32 SampleBits;
    TtakInt32 ChannelNum;
    TtakInt32 BlockSize;
} TtakAudioFormat;

Felder:

DataType

Aktuell immer = tak_AudioFormat_DataType_PCM.

SampleRate

Samples pro Sekunde (pro Kanal).

SampleBits

Bits pro Sample.

ChannelNum

Anzahl der Kanäle.

BlockSize

= ChannelNum * ((SampleBits + 7) / 8)

Für mehr als 2 Kanäle wird diese Struktur erweitert werden.

Codecs und Presets

function tak_GetCodecName

Liefert den Namen eines Codecs.

Pascal:

function tak_GetCodecName (ACodec    : TtakInt32;
                           AName     : PChar;
                           ANameSize : TtakInt32) : TtakResult; cdecl;

C:

TtakResult tak_GetCodecName (TtakInt32 ACodec,
                             char *    AName,
                             TtakInt32 ANameSize);

Liefert in AName einen Klartextnamen für ACodec. ANameSize ist die Größe von AName in Bytes und sollte wenigstens tak_CodecNameLenSize sein.

Spezielle Funktionsergebnisse:

tak_res_IncompatibleVersion

ACodec ist unbekannt, AName undefiniert.

type TtakPresets

Encoder-Presets.

Pascal:

type
  TtakPresets = TtakInt32;

C:

typedef TtakInt32 TtakPresets;

type TtakPresetEvaluations

Preset-Evaluation.

Pascal:

type
  TtakPresetEvaluations = TtakInt32;

C:

typedef TtakInt32 TtakPresetEvaluations;

Folgende Werte sind möglich:

tak_PresetEval_Standard

tak_PresetEval_Extra

tak_PresetEval_Max

TAK's Preset-Evaluationen Standard bis Max.

Stream / Container

const tak_FrameSizeMax = 16384

Maximale Sampleanzahl eines Frames.

const tak_FrameDurationMax = 250

Maximale Framedauer in ms.

const tak_str_SimpleWaveDataSizeMax = 1024 * 1024

Maximalgröße von Wave-Metadaten.

type Ttak_str_EncoderInfo

Informationen über den verwendeten Codec.

Pascal:

type
  Ttak_str_EncoderInfo = packed record
    Codec   : TtakInt32;
    Profile : TtakPresets;
  end;

C:

typedef struct Ttak_str_EncoderInfo {
    TtakInt32   Codec;
    TtakPresets Profile;
} Ttak_str_EncoderInfo;

Felder:

Codec

Codec-Typ. Bereich: 0-63.

In TAK 1.0 ist dieser Wert immer 0. Andere Werte sind möglich, wenn ich neue Codecs hinzufüge oder eine Fehlerkorrektur eines bestehenden Codecs zu Inkompatibilitäten mit älteren Decodern führt.

tak_GetCodecName liefert den Namen eines Codecs.

Profile

Hardwareprofil, ggfs. Codec-spezifisch.

Sofern der Anwender die Standardeinstellungen der vordefinierten Presets verwendet hat, entspricht der Wert dem gewählten Preset.

Profile definieren Leistungsanforderungen an den Decoder. Die relevanten Parameter sind:

Wählt der Anwender z.B. das Preset TURBO und erhöht die Prediktoranzahl von 16 auf 128, wird als Profil HIGH gespeichert.

type TtakFrameSizeTypes

TAK definiert eine begrenzte Anzahl von Framegrößentypen, die entweder die Framedauer in ms oder die Framegröße in Samples angeben.

Pascal:

type
  TtakFrameSizeTypes = TtakInt32;

C:

typedef TtakInt32 Ttak_str_FrameSizeTypes;

Mögliche Werte:

tak_FrameSizeType_94_ms

tak_FrameSizeType_125_ms

tak_FrameSizeType_188_ms

tak_FrameSizeType_250_ms

Framegröße in ms.

tak_FrameSizeType_4096

tak_FrameSizeType_8192

tak_FrameSizeType_16384

tak_FrameSizeType_512

tak_FrameSizeType_1024

tak_FrameSizeType_2048

tak_FrameSizeType_6144

tak_FrameSizeType_12288

Framegröße in Samples.

Standardmäßig werden Framegrößen als Zeitwerte spezifiziert. Nur in zwei Fällen wird davon abgewichen:

type Ttak_str_SizeInfo

Informationen über Größenparameter.

Pascal:

type
  Ttak_str_SizeInfo = packed record
    FrameSize          : TtakFrameSizeTypes;
    FrameSizeInSamples : TtakInt32;
    SampleNum          : TtakInt64;
  end;

C:

typedef struct Ttak_str_SizeInfo {
    Ttak_str_FrameSizeTypes FrameSize;
    TtakInt32               FrameSizeInSamples;
    TtakInt64               SampleNum;
} Ttak_str_SizeInfo;

Felder:

FrameSize

Framegrößentyp.

FrameSizeInSamples

Framegröße in Samples. Bereich: 1 bis 16384.

SampleNum

Streamlänge in Samples.

Die maximale Länge für TAK 1.0 paßt immer in einen (unsigned) long.

Siehe auch:

TtakFrameSizeTypes

type Ttak_str_StreamInfo

Faßt alle für das Dekodieren benötigten Informationen über einen Stream zusammen.

Pascal:

type
  Ttak_str_StreamInfo = packed record
    Encoder : Ttak_str_EncoderInfo;
    Sizes   : Ttak_str_SizeInfo;
    Audio   : TtakAudioFormat;
  end;

C:

typedef struct Ttak_str_StreamInfo {
    Ttak_str_EncoderInfo Encoder;
    Ttak_str_SizeInfo    Sizes;
    TtakAudioFormat      Audio;
} Ttak_str_StreamInfo;

Siehe auch:

Ttak_str_EncoderInfo, Ttak_str_SizeInfo, TtakAudioFormat

type Ttak_str_SimpleWaveDataHeader

Beschreibung der Metadatenbereiche einer Wavedatei.

Pascal:

type
  Ttak_str_SimpleWaveDataHeader = packed record
    HeadSize : TtakInt32;
    TailSize : TtakInt32;
  end;

C:

typedef struct Ttak_str_SimpleWaveDataHeader {
    TtakInt32 HeadSize;
    TtakInt32 TailSize;
} Ttak_str_SimpleWaveDataHeader;

Felder:

HeadSize

Göße des Waveheaders in Bytes.

TailSize

Größe der Metadaten, die ggfs. am Dateiende auf die Audiodaten folgten.

type Ttak_str_MetaEncoderInfo

Informationen über den verwendeten Encoder.

Pascal:

type
  Ttak_str_MetaEncoderInfo = packed record
    Version    : TtakInt32;
    Preset     : TtakPresets;
    Evaluation : TtakPresetEvaluations;
  end;

C:

typedef struct Ttak_str_MetaEncoderInfo {
    TtakInt32             Version;
    TtakPresets           Preset;
    TtakPresetEvaluations Evaluation;
} Ttak_str_MetaEncoderInfo;

Felder:

Version

Die dreistellige Versionsnummer des Encoders. Jede Stelle ist ein Byte groß, die niedrigste Stelle steht im niedrigsten Byte. Beispiel: 00010000h = 1.0.0

Preset

Encoder-Preset.

Evaluation

Preset-Evaluation.

Siehe auch:

TtakPresets, TtakPresetEvaluations