| I recently added some changes to CVS that call a new host callback whenever
Csound opens a file using the standard csoundFileOpen() interface. The
purpose of the callback is to provide a path and other information for each
opened file and has a number of potential uses by host applications.
In order to provide some of the information that I wanted this callback to
make available, it would have been necessary to modify the csoundFileOpen()
and csound->FileOpen() calls. To avoid an incompatible change in the API, I
decided -- at least temporarily -- to create a new function pointer
csound->FileOpen2() and to make the original function call this new function
behind the scenes with some "dummy" data. I've marked the original
FileOpen() pointer with the comment "/* Do not use FileOpen in new code; it
has been replaced by FileOpen2 */", but this comment can be changed.
Here are the signatures of these calls:
/* this is called by csound->FileOpen() */
void *csoundFileOpen(CSOUND *csound, void *fd, int type,
const char *name, void *param, const char *env)
/* this is called by csound->FileOpen2() */
void *csoundFileOpenWithType(CSOUND *csound, void *fd, int type,
const char *name, void *param, const char *env,
int csFileType, int isTemporary)
Here is a description of the new parameters:
* int csFileType:
* A value from the enumeration CSOUND_FILETYPES (see CsoundCore.h)
* int isTemporary:
* TRUE if this file will be deleted when Csound is finished.
* Otherwise, FALSE.
*/
csoundFileOpen() simply calls csoundFileOpenWithType() with csFileType set
to CSFTYPE_UNKNOWN and isTemporary set to FALSE (will be 0 once I change
it).
There is also a new host API function, csoundSetFileOpenCallback(), for
setting a callback function described as:
/**
* Sets an external callback for receiving notices whenever Csound opens
* a file. The callback is made after the file is successfully opened.
* The following information is passed to the callback:
* char* pathname of the file; either full or relative to current dir
* int a file type code from the enumeration CSOUND_FILETYPES
* int 1 if Csound is writing the file, 0 if reading
* int 1 if a temporary file that Csound will delete; 0 if not
*
* Pass NULL to disable the callback.
* This callback is retained after a csoundReset() call.
*/
PUBLIC void csoundSetFileOpenCallback(CSOUND *p,
void (*func)(CSOUND*, const char*, int, int, int));
So, some questions regarding the new facilty:
- Is the additional FileOpen2() call the best way to go or should we replace
the original? If not replaced, should the original FileOpen() be marked as
deprecated?
- Is there other information that would be useful for the FileOpenCallback
to pass to the host? Some possibilities might include:
- the name of the environment variable (SFDIR, etc.) where Csound found
the file that was opened.
- for audio files and other "streams of numbers" files (such as those
written by the dumpk opcode), would it be useful to tell the host the
the sample rate, number of channels, bit-width of samples, etc. ??
- I've included the complete list of CSOUND_FILETYPES that I've added so far
at the end of this message. What other file type codes could we use or do
you think any of the existing ones are not necessary? (I am not sure that
we need codes for VST and LADSPA plugins, for example; I was considering
adding codes for script files such as Python scripts run by the pyexec
opcode).
- I have only included audio file constants for the file types that Csound
can write; so I have left out some of the more obscure formats that it can
read and I was thinking of using CSFTYPE_UNKNOWN_AUDIO when one of the these
file types is opened for reading. I could add more constants to the
enumeration if you think they would be useful.
Currently, I have modified all csound->FileOpen() calls within Csound itself
and most of the standard plugins. However, there are a number of files
opened directly with fopen() and most of these should probably be changed.
In addition, files opened by other facilities such as ldmemfile() and
csoundLoadSoundFile() currently do not cause the FileOpenCallback to be
activated. It will be necessary to modify these facilities, perhaps adding
a csound->ldmemfile2() function pointer to the CSOUND struct.
Your feedback concerning these changes would be very much appreciated.
Thanks.
Anthony
/**
* The following constants are used with csound->FileOpen2() and
* are passed by Csound to a host's FileOpen callback.
*/
typedef enum
{
CSFTYPE_UNIFIED_CSD = 1, /* Unified Csound document */
CSFTYPE_ORCHESTRA = 2, /* the primary orc file (may be temporary) */
CSFTYPE_SCORE = 3, /* the primary sco file (may be temporary) */
CSFTYPE_ORC_INCLUDE = 4, /* a file #included by the orchestra */
CSFTYPE_SCO_INCLUDE = 5, /* a file #included by the score */
CSFTYPE_SCORE_OUT = 6, /* used for score.srt, score.xtr, cscore.out
*/
CSFTYPE_SCOT = 7, /* Scot score input format */
CSFTYPE_OPTIONS = 8, /* for .csoundrc and -@ flag */
/* audio file types that Csound can write */
CSFTYPE_RAW_AUDIO = 9,
CSFTYPE_IRCAM = 10,
CSFTYPE_AIFF = 11,
CSFTYPE_WAVE = 12,
CSFTYPE_AU = 13,
CSFTYPE_SD2 = 14,
CSFTYPE_W64 = 15,
CSFTYPE_WAVEX = 16,
CSFTYPE_FLAC = 17,
CSFTYPE_UNKNOWN_AUDIO = 18, /* used when opening audio file for reading
or temp file written with */
/* miscellaneous music formats */
CSFTYPE_SOUNDFONT = 19,
CSFTYPE_STD_MIDI = 20, /* Standard MIDI file */
CSFTYPE_MIDI_SYSEX = 21, /* Raw MIDI codes, eg. SysEx dump */
/* analysis formats */
CSFTYPE_HETRO = 22,
CSFTYPE_PVC = 23, /* original PVOC format */
CSFTYPE_PVCEX = 24, /* PVOC-EX format */
CSFTYPE_CVANAL = 25,
CSFTYPE_LPC = 26,
CSFTYPE_ATS = 27,
CSFTYPE_LORIS = 28,
CSFTYPE_SDIF = 29,
/* Types for plugins and the files they read/write */
CSFTYPE_VST_PLUGIN = 30,
CSFTYPE_LADSPA_PLUGIN = 31,
CSFTYPE_SNAPSHOT = 32,
/* Special formats for Csound ftables with header info */
CSFTYPE_FTABLES_TEXT = 33, /* for ftsave and ftload */
CSFTYPE_FTABLES_BINARY = 34, /* for ftsave and ftload */
/* These are for raw lists of numbers without header info */
CSFTYPE_FLOATS_TEXT = 35, /* used by GEN23, GEN28, dumpk, readk */
CSFTYPE_FLOATS_BINARY = 36, /* used by dumpk, readk, etc. */
CSFTYPE_INTEGER_TEXT = 37, /* used by dumpk, readk, etc. */
CSFTYPE_INTEGER_BINARY = 38, /* used by dumpk, readk, etc. */
/* For files that don't match any of the above */
CSFTYPE_POSTSCRIPT = 39, /* EPS format used by graphs */
CSFTYPE_OTHER_TEXT = 40,
CSFTYPE_OTHER_BINARY = 41,
/* This should only be used internally by the original FileOpen()
API call or for temp files written with */
CSFTYPE_UNKNOWN = 0
}
CSOUND_FILETYPES;
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net |