Reading and Changing Audio Item Attributes

Many Audio folio items have attributes that must be changed after the item has been created. For example, a sample created for use with a multisample instrument can be changed so that its pitch or velocity range can be limited. Because items are system resources, a task cannot alter them directly. To provide a task with the ability to change audio items, the Audio folio provides one call that reads an item's current settings and a second call that changes an item's current settings. These calls work with sample, envelope, attachment, knob, and tuning items.

Reading Audio Item Characteristics

To read the current tag argument values for a sample, envelope, attachment, tuning, or knob item, use this call:

Err GetAudioItemInfo( Item AnyItem, TagArg *tp )

The call accepts the item number of the item for which you want information, and a pointer to a list of tag arguments. You must set up the tag argument list before you use the call. You should include any of the item's tag arguments in which you are interested, anywhere from only one tag argument to all of the appropriate tag arguments. (The tag arguments are listed in the description of SetAudioItemInfo() in Audio Folio Calls, of the 3DO Music and Audio Programmer's Reference. They are also described in Setting an Attachment's Attributes.)

When GetAudioItemInfo() executes, it finds the current value for each of the tag arguments in the list and writes that value to the tag argument. The call returns 0 if successful, or a negative number (an error code) if unsuccessful.

To get the information you asked for, read the values written into your tag argument list. (To make sure that each value is written, it is wise to initially set the tag argument values to NULL. GetAudioItemInfo() writes over the original values.)

Setting Audio Item Characteristics

To change the characteristics of a sample, envelope, attachment, or tuning item, (but not a knob item), use this call:

Err SetAudioItemInfo( Item AnyItem, TagArg *TagList )

The call accepts the item number of the item you want to change. It also accepts a pointer to a list of tag arguments that you must set up before you use the call. The tag argument values you supply in the list determine the characteristics of the item. (The tag arguments are described in Audio Folio Calls, of the 3DO Music and Audio Programmer's Reference under the description of SetAudioItemInfo().) You can also use SetAudioItemInfoVA(). See Audio Folio Calls of the 3DO Music and Audio Programmer's Reference for more information.

When SetAudioItemInfo() executes, it reads the tag argument values in the tag argument list and applies them to the specified item. It returns 0 if successful, or a negative value (an error code) if unsuccessful.

Note that this call does not work with any audio items other than sample, envelope, attachment, or tuning items.