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.
|