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.


     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
     AU_PVTYPE_LONG from an instrument configuration.

     afSetInstParamLong() allows you to set an instrument parameter of type
     AU_PVTYPE_LONG for a file which is opened with write access.

     The valid instrument parameters are:

     AF_INST_MIDI_BASENOTE     MIDI base note for sample: 0 to 127

     AF_INST_NUMCENTS_DETUNE   MIDI detune in cents: -50 to 50 for AIFC;
                               limits vary with file format

     AF_INST_MIDI_LONOTE       Lowest MIDI note for sample: 0 to 127

     AF_INST_MIDI_HINOTE       Highest MIDI note for sample: 0 to 127

     AF_INST_MIDI_LOVELOCITY   Lowest MIDI velocity for sample: 1 to 127

     AF_INST_MIDI_HIVELOCITY   Highest MIDI velocity for sample: 1 to 127

     AF_INST_NUMDBS_GAIN       Gain in dB's for sample

     AF_INST_SUSLOOPID         Loop id for sustain loop (AIFF and AIFF-C only)

     AF_INST_RELLOOPID         Loop id for release loop (AIFF and AIFF-C only)

     Additional instrument parameters (for non-AIFF files):

     AF_INST_SAMP_STARTFRAME   Starting frame of sample associated with the
                               inst: 0 or greater

     AF_INST_SAMP_ENDFRAME     Ending frame of sample associated with the
                               inst: 0 or greater

     AF_INST_SAMP_MODE         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

     AF_INST_TRACKID
          Track ID for inst sample data:  AF_DEFAULT_TRACK

     AF_INST_NAME
          Name string for instrument configuration.  This is type
          AU_PVTYPE_PTR.


     AF_INST_SAMP_RATE
          Sample rate for sample associated with the inst.  This is type
          AU_PVTYPE_DOUBLE

     Note that the last two are NOT AU_PVTYPE_LONG 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 AU_PVTYPE_LONG, 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