Miles Sound System SDK 7.2a

AIL_enumerate_output_filter_driver_properties

The function AIL_enumerate_output_filter_driver_properties enumerates the possible driver-level properties of an output filter.

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

In Parameters

filter: specifies the output filter whose driver-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_driver_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" which is a pointer to the property name, which can then be used in the AIL_output_filter_driver_property function.

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. Most applications will never need to work with output filter controls directly, but those that wish to do so can obtain a handle to the current voice or matrix output filter from AIL_digital_output_filter and access provider- and driver-level properties via the AIL_filter_property and AIL_output_filter_driver_property functions.

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 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.

Driver-level properties are properties that apply globally to a particular filter. For properties that are specific to each sample (sample-level properties) played by an output filter, use the AIL_enumerate_sample_stage_properties function with the SP_OUTPUT stage.

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.

Example files that use this function: examms.cpp

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