afGetInstParamLong(3dm) afGetInstParamLong(3dm)
NAME
afGetInstParams, afSetInstParams, afGetInstParamLong, afSetInstParamLong
- get / set a parameter list / long parameter value for an instrument
configuration in an AFfilehandle structure
SYNOPSIS
#include <dmedia/audiofile.h>
void afGetInstParams(AFfilehandle file, int instid,
AUpvlist pvlist, int nparams)
void afSetInstParams(AFfilehandle file, int instid,
AUpvlist pvlist, int nparams)
long afGetInstParamLong(AFfilehandle file, int instid,
int param)
void afSetInstParamLong(AFfilehandle file, int instid,
int param, long value)
PARAMETER
file is an AFfilehandle structure, previously created by a call to
afOpenFile(3dm).
instid is a positive integer which identifies an instrument
configuration in the file. Since the number of supported inst
chunks varies with file format, applications should always
retrieve this value via afGetInstIDs(3dm).
pvlist is an AUpvlist structure, previously created by a call to
AUpvnew(3dm)
nparams is an integer value specifying the number of {parameter, value}
item pairs (containing the instrument parameters) to be set or
retrieved
param is a symbolic constant which identifies an instrument
parameter.
value is an integer value to be assigned by afSetInstParamLong() to
the given parameter.
RETURN VALUE
afGetInstParamLong() returns the value associated with param in the given
instrument map. If inst or param is invalid, the return value is 0.
Note that this routine and afQueryLong(3dm) are the only AF routines
which still return a long int as opposed to an int.
DESCRIPTION
afGetInstParams() returns the values for nparams of the parameters in an
instrument configuration via the AUpvlist structure.
Page 1
afGetInstParamLong(3dm) afGetInstParamLong(3dm)
afSetInstParams() allows you to set nparams instrument parameters, via
the AUpvlist structure, for a file which is opened with write access.
afGetInstParamLong() returns the value for a parameter of type
AUPVTYPELONG from an instrument configuration.
afSetInstParamLong() allows you to set an instrument parameter of type
AUPVTYPELONG for a file which is opened with write access.
The valid instrument parameters are:
AFINSTMIDIBASENOTE MIDI base note for sample: 0 to 127
AFINSTNUMCENTSDETUNE MIDI detune in cents: -50 to 50 for AIFC;
limits vary with file format
AFINSTMIDILONOTE Lowest MIDI note for sample: 0 to 127
AFINSTMIDIHINOTE Highest MIDI note for sample: 0 to 127
AFINSTMIDILOVELOCITY Lowest MIDI velocity for sample: 1 to 127
AFINSTMIDIHIVELOCITY Highest MIDI velocity for sample: 1 to 127
AFINSTNUMDBSGAIN Gain in dB's for sample
AFINSTSUSLOOPID Loop id for sustain loop (AIFF and AIFF-C only)
AFINSTRELLOOPID Loop id for release loop (AIFF and AIFF-C only)
Additional instrument parameters (for non-AIFF files):
AFINSTSAMPSTARTFRAME Starting frame of sample associated with the
inst: 0 or greater
AFINSTSAMPENDFRAME Ending frame of sample associated with the
inst: 0 or greater
AFINSTSAMPMODE Sample looping mode associated with the inst.
If this parameter is present, it will be one of
the following:
AF_INST_LOOP_OFF
AF_INST_LOOP_CONTINUOUS
AF_INST_LOOP_SUSTAIN
AFINSTTRACKID
Track ID for inst sample data: AF_DEFAULT_TRACK
AFINSTNAME
Name string for instrument configuration. This is type
AUPVTYPEPTR.
Page 2
afGetInstParamLong(3dm) afGetInstParamLong(3dm)
AFINSTSAMPRATE
Sample rate for sample associated with the inst. This is type
AUPVTYPEDOUBLE
Note that the last two are NOT AUPVTYPELONG and therefor cannot be set
or retrieved via af{Set,Get}InstParamLong() -- you must use
afGetInstParams() and retrieve the value using AUpvgetval(3dm).
EXAMPLE
You can obtain loop ID's for the sustain and release loops in an AIFF-C
file by calling afGetInstParamLong().
For each of these loop ID's, you can obtain start and end sample frame
marker ID's by calling afGetLoopStart(3dm) and afGetLoopEnd(3dm).
Finally, you can obtain the sample frame marker positions by calling
afGetMarkPosition(3dm). These positions tell you the beginning and end
sample frame locations for each of the loops.
CAVEATS
This function may return an arbitrary number of instrument parameters,
unlike the fixed set found in AIFF/AIFF-C files. Many file formats have
different inst configurations than AIFF/AIFF-C. As mentioned above,
parameters exist whose type is not AUPVTYPELONG, and these must be
retrieved via afGetInstParams(3dm).
In the case of INST parameters it is important to to query at runtime the
capabilities of a given file format prior to retrieving the params. An
application can use afQuery(3dm) to determine whether a given file format
supports INST chunks, and if so, the quantity, ID, and return type of any
instrument parameters. Apps should also be written to expect and ignore
instrument configurations or instrument parameters they do not
understand.
SEE ALSO
afOpenFile(3dm), afGetLoopStart(3dm), afSetLoopStart(3dm),
afGetMarkPosition(3dm), afQuery(3dm)
Page 3