[openal] ALC_SOFT_pause_device proposal

[Chris Robinson]

Here's the last feature I'd like have done for 1.16. This extension is 
mainly for mobile apps, which should stop audio output when in the 
background (to avoid draining the battery), and resume when it comes 
back to the foreground. There doesn't seem to be a consistent way to do 
this between implementations (iOS seems to use alcSuspendContext, and 
some others go silent after alcMakeContextCurrent(NULL)), so explicit 
functions are probably the best way to go about it.
-------------- next part --------------
Name

    ALC_SOFT_pause_device

Contributors

    Chris Robinson

Contact

    Chris Robinson (chris.kcat 'at' gmail.com)

Status

    In progress.

Dependencies

    This extension is written against the OpenAL 1.1 specification.
    This extension trivially interacts with ALC_SOFT_loopback

Overview

    This extension allows applications to pause a playback device. The main
    purpose of this is to silence output, stop processing, and allow the audio
    hardware to go into a low-power mode. On a mobile device, for instance,
    apps may want to silence output and not waste battery life with unneeded
    processing when in the background.

Issues

    None.

New Procedures and Functions

    void alcDevicePauseSOFT(ALCdevice *device);

    void alcDeviceResumeSOFT(ALCdevice *device);

New Tokens

    None.

Additions to Specification

    Pausing Playback

    A playback device may be paused with the function

    void alcDevicePauseSOFT(ALCdevice *device);

    When paused, no contexts associated with the device will be processed or
    updated. Playing sources will not produce sound, have their offsets
    incremented, or process any more buffers, until the device is resumed.
    Pausing a device that is already paused is a legal no-op.

    To resume playback of a paused device, use the function

    void alcDeviceResumeSOFT(ALCdevice *device);

    This will restart processing on the device -- that is, sources will resume
    playing sound as normal. Resuming playback on a device that is not paused
    is a legal no-op.

    These functions are not reference counted. alcDeviceResumeSOFT only needs
    to be called once to resume playback, regardless of how many times
    alcDevicePauseSOFT was called.

Errors

    An ALC_INVALID_DEVICE error is generated if NULL or an invalid device
    handle is passed to alcDevicePauseSOFT or alcDeviceResumeSOFT.

    An ALC_INVALID_DEVICE error is generated if the device handle passed to
    alcDevicePauseSOFT or alcDeviceResumeSOFT is for a non-playback device
    (i.e. capture or loopback).