NAME

Snack_CreateFileFormat - define new sound file format

SYNOPSIS

#include <snack.h>
Snack_CreateFileFormat(format)

ARGUMENTS

Snack_FileFormat *format

typedef struct Snack_FileFormat {
  char                               *name;
  guessFileTypeProc      *guessProc;
  getHeaderProc             *getHeaderProc;
  extensionFileTypeProc *extProc;
  putHeaderProc             *putHeaderProc;
  openProc                      *openProc;
  closeProc                      *closeProc;
  readSamplesProc          *readProc;
  writeSamplesProc         *writeProc;
  seekProc                       *seekProc;
  freeHeaderProc          *freeHeaderProc;
  configureProc            *configureProc;
  struct Snack_FileFormat *nextPtr;
} Snack_FileFormat;

char *name

char *guessFileTypeProc (char *buf, int len)

int  getHeaderProc (Sound *s, Tcl_Interp *interp, Tcl_Channel ch, Tcl_Obj *obj, char *buf)

char *extensionFileTypeProc (char *buf);

int  putHeaderProc (Sound *s, Tcl_Interp *interp, Tcl_Channel ch, Tcl_Obj *obj, int objc, Tcl_Obj *CONST objv[], int length)

int  openProc (Sound *s, Tcl_Interp *interp,Tcl_Channel *ch, char *mode)

int  closeProc (Sound *s, Tcl_Interp *interp, Tcl_Channel *ch)

int  readSamplesProc (Sound *s, Tcl_Interp *interp, Tcl_Channel ch, char *inBuffer, float *outBuffer, int length)

int  writeSamplesProc (Sound *s, Tcl_Channel ch, Tcl_Obj *obj, int start, int length)

int  seekProc (Sound *s, Tcl_Interp *interp, Tcl_Channel ch, int position)

void freeHeaderProc (Sound *s)

int  configureProc(Sound *s, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[])
 

DESCRIPTION

Snack_CreateFileFormat is used to define a new kind of sound file format. A number of procedures can be specified in a Snack_FileFormat structure to handle sound data I/O, header parsing, etc. The file SphereFile.c serves as good example of how these routines are intended to be used.

The string name will be returned as the result of a successful read command.

guessFileTypeProc is invoked by Snack in order to find out if the current file is of a type which this handler recognizes. guessFileTypeProc will receive buffer filled with bytes from the header up to length and if it recognizes the format is should return formatName. If it can't make a decision after seeing only length bytes it should return the string QUE_STRING. It will subsequently be invoked again with some more bytes for a new try. If the file is clearly in another format guessFileTypeProc should return NULL.

extensionFileTypeProc takes a filename string and returns formatName if its file name extension matches its format else it return NULL.  This is used when saving a sound object using a filename to guess which format it should be saved with. If no save functionality is needed and extensionFileTypeProc is specified as NULL, a raw file will be saved using filename, which could be confusing. By providing an extensionFileTypeProc for the format Snack will be able to report "unsupported save format".

getHeaderProc is invoked in order to decode a sound file header. If the sound file resides on disk ch will be a a channel opened for reading, otherwise it will be NULL. If the sound resides in memory obj will point to a binary Tcl variable containing the data of the sound file, otherwise it will be NULL. The procedure should use these macros to specify the properties of the sound file
Snack_SetSampleRate()
Snack_SetNumChannels()
Snack_SetSampleEncoding()
Snack_SetBytesPerSample()
Snack_SetHeaderSize()
Snack_SetLength()
On success getHeaderProc should TCL_OK, otherwise it should return TCL_ERROR and leave an error message in the Tcl result.

putHeaderProc is invoked in order to decode a sound file header. If the sound file is to be written to disk, ch will point to a channel opened for writing, otherwise it will be NULL. If the sound file is to be written to a Tcl binary variable, obj will point to a Tcl Obj, otherwise it will be NULL. The length argument will contain the length of the sound data in sample frames.

openProc, closeProc, readSamplesProc, writeSamplesProc, and seekProc are modelled after their Tcl channel equivalents. readSamplesProc should read data either from ch or inBuffer which ever is not equal to NULL. The length argument is given in samples (not frames) and the return value is the number of samples read (or -1 if an error occurred). seekProc should seek in the sound file to the sample frame given by the position argument.

freeHeaderProc is called when a new file is read into a sound object or when it is destroyed. It is used to deallocate ant memory which might have been allocated earlier in, e.g., openProc.