Miles Sound System SDK 7.2a

AIL_enumerate_output_filter_sample_properties

The function AIL_enumerate_output_filter_sample_properties enumerates the possible sample-level properties of an output filter.

S32 AIL_enumerate_output_filter_sample_properties(
  HPROVIDER filter,
  HINTENUM *next,
  RIB_INTERFACE_ENTRY *dest
);

In Parameters

filter: specifies the output filter whose sample-level properties should be enumerated.

Out Parameters

next: is a pointer that MSS uses to keep track of the next property to return. You initialize the next variable with the constant HINTENUM_FIRST before the first call to AIL_enumerate_output_filter_sample_properties.
dest: points to an structure of type RIB_INTERFACE_ENTRY that receives the property information. The most important field in this RIB structure is "entry_name". This is a pointer to the property name, which can be used in calls to the AIL_sample_stage_property function for the sample's SP_OUTPUT stage.

Returns

0 if no further properties were found; non-zero if another property was found.

Discussion

Certain digital sound configurations, including DirectSound3D, EAX, Dolby Surround, DTS, and SRS Circle Surround(r), are implemented with internal extension modules called output filters. Output filters can offer additional control options beyond those available from the core MSS API.

Sample-level properties are properties that apply to an individual HSAMPLE being processed or played by a particular filter.

Sample-level properties may be accessed through calls to AIL_sample_stage_property with the SP_OUTPUT stage identifier. Sample-level property control is available only for hardware voice filters such as DirectSound3D and EAX, not matrix filters such as Dolby.

You can find a list of configuration-specific properties in the chapter on the specific output filter you are using. See the examms demo program for an example of how to enumerate and query provider-level, driver-level, and sample-level properties.

You can get the HPROVIDER handle corresponding to a driver's matrix or per-voice output filter, if any, by calling AIL_digital_output_filter.

Prior to MSS 7, 3D driver properties were accessed at the HPROVIDER level. In MSS 7, a given HPROVIDER may provide 3D services for a number of HDIGDRIVERS at once. Consequently, very few provider-level properties are associated with output filters other than the filter's name and version.

You can also obtain a list of sample-specific output filter properties by calling the AIL_enumerate_sample_stage_properties function for the SP_OUTPUT stage of a given HSAMPLE. However, AIL_enumerate_output_filter_sample_properties works even without a valid HSAMPLE.

Example files that use this function: examms.cpp

Group: Digital Audio Services
Related Functions: AIL_digital_output_filter, AIL_enumerate_output_filter_sample_properties, AIL_enumerate_sample_stage_properties, AIL_output_filter_driver_property, AIL_sample_stage_property
Related Basic Types: HINTENUM, HPROVIDER, S32
Related Structures: RIB_INTERFACE_ENTRY