libao documentation | libao version 1.2.0 - 201401271

# ao_plugin_device_init

declared in "ao/plugin.h";

Initialize the private device data structures. Memory should be allocated, and default values set if necessary, but devices should not be opened until ao_plugin_open() is called.

Drivers that wish to support automatic surround channel mapping should set `device->output_matrix_order` to one of:

- AO_OUTPUT_MATRIX_FIXED - The audio driver outputs a fixed channel order that is always the same for a given number of channels and can't be changed. One example is ALSA where to play to the side right speaker, it is necessary to open eight channels and write to side right as channel eight, even if the other seven channels are unused.
- AO_OUTPUT_MATRIX_COLLAPSIBLE - The audio driver outputs a fixed channel order that is always the same, but unused channels are not sent. In such a driver with the channel order 'L,R,C,LFE,BL,BR', we can write to the two rear speakers without opening six channels but the rear speakers must still be in the order 'BL,BR'. Such drivers usually use a bitmap to represent the channels present in the output. Examples are wav, wmm and macosx.
- AO_OUTPUT_MATRIX_PERMUTABLE - Channels may be arranged in any order. An example of such a driver is pulse.

In addition, a driver may set `device->output_matrix` to the list of possible output channels in order. Note that even AO_OUTPUT_MATRIX_PERMUTABLE drivers usually have a fixed numbering scheme for channels even if the channels may be sent in any order. A driver that is unable to set an output matrix without inspecting the input sample format (for example, the roar driver), may set `device->output_matrix_order` to `AO_OUTPUT_MATRIX_FIXED` and delay channel mapping initialization until ao_plugin_open().

    int ao_plugin_device_init(ao_device *device);

### Parameters

device
  Pointer to pre-allocated device structure. The driver should store the address of its private memory in `device->internal`.

### Return Values

> - 1 indicates success.
> - 0 indicates failure, probably due to memory allocation problems. ao_plugin_device_clear() should be called to ensure the deallocate of all private data structures.

copyright © 2001-2003 Stan Seibert, 2010-2011 Monty | xiph.org monty@xiph.org
libao documentation | libao version 1.2.0 - 201401271