CreateInsTemplate

Generic template creation function.

Synopsis

Item CreateInsTemplate (TagArg *tagList)

Item CreateInsTemplateVA (uint32 tag1, ...)

Description

This is the general function to create an instrument Template. It is used internally by all the other template creation functions (e.g. LoadInsTemplate(), DefineInsTemplate(), etc) to actually perform the template creation. Use it if you need to do something that these other functions don't provide.

Call UnloadInsTemplate() to dispose of the Item created by this function.

Arguments

None

Tags to Load Template File Required:

AF_TAG_NAME: (const char *) Name of template file to load.

Optional:

AF_TAG_DEVICE: (Item) Audio device Item for instrument template. 0 indicates the default audio device, the DSP, which is the only valid audio device item at the present time. Conveniently defaults to 0, so you should never need to use this tag.

AF_TAG_ALLOC_FUNCTION: (void *(*)(uint32 memsize, uint32 memflags)) Sets custom memory allocation function to be called during template creation for objects that can be created in user memory. Currently this only applies to samples embedded in ARIA instruments. Defaults to AllocMem(). If you supply a custom allocation function you must also provide a custom free function with AF_TAG_FREE_FUNCTION.

AF_TAG_FREE_FUNCTION: (void (*)(void *memptr, uint32 memsize)) Sets custom memory free function to be called during template deletion. Defaults to FreeMem(). If you supply a custom free function you must also provide a custom allocation function with AF_TAG_ALLOC_FUNCTION.

Tags to Parse Template File Image in Memory Required:

AF_TAG_IMAGE_ADDRESS: (const char *) Specifies a memory location containing a template file image from which to read instrument template. Unless AF_TAG_LEAVE_IN_PLACE is set, this memory does not need to remain valid after calling CreateInsTemplate(). Must use in conjunction with AF_TAG_IMAGE_LENGTH.

AF_TAG_IMAGE_LENGTH: (uint32) Specifies number of bytes in template file image pointed to by AF_TAG_IMAGE_ADDRESS.

Optional:

AF_TAG_DEVICE: (Item) See above.

AF_TAG_ALLOC_FUNCTION: (void *(*)(uint32 memsize, uint32 memflags)) See above. Mutually exclusive with AF_TAG_LEAVE_IN_PLACE.

AF_TAG_FREE_FUNCTION: (void (*)(void *memptr, uint32 memsize)) See above.

AF_TAG_LEAVE_IN_PLACE: (bool) When TRUE causes any objects that would otherwise be copied to user memory to be left in place. Currently this only applies to samples embedded in an ARIA instrument. See CreateSample() for more information and caveats regarding this tag. This is potentially useful for ARIA instruments that contain large samples, but otherwise is not too helpful, mainly because you must leave the entire template file image in memory regardless of how little of that memory is actually used for samples. Defaults to FALSE. Mutually exclusive with AF_TAG_ALLOC_FUNCTION.

Return Value

The procedure returns an instrument Template Item number (a positive value) if successful or an error code (a negative value) if an error occurs.

Implementation

Folio call implemented in audio folio V20.

Caveats

Ideally there should be a DeleteInsTemplate() function, but there isn't one yet. Sorry for any confusion that might arise from pairing CreateInsTemplate() with UnloadInsTemplate().

Examples

    // These two calls are equivalent
LoadInsTemplate ("directout.dsp", 0);
CreateInsTemplateVA ( AF_TAG_NAME, "directout.dsp",TAG_END);

   // These two calls are also equivalent
DefineInsTemplate (dspFileImage, dspFileLength, 0, "foo.dsp");
CreateInsTemplateVA ( AF_TAG_IMAGE_ADDRESS, dspFileImage,AF_TAG_IMAGE_LENGTH,  dspFileLength, TAG_END);

Associated Files

audio.h