Name ALC_SOFT_device_clock Contributors Chris Robinson Contact Chris Robinson (chris.kcat 'at' gmail.com) Status Complete Dependencies This extension is written against the OpenAL 1.1 specification. This extension requires AL_SOFT_source_latency. This extension interacts with ALC_SOFT_pause_device. Overview This extension allows applications to query the timing clock from the audio device. This clock lets applications measure the passage of time as the audio device sees it, which may be slightly different than the system clock's tick rate (the infamous timer drift). Issues None. New Primitive Types ALC Type Description GL Type ============= ==================================== ======== ALCint64SOFT Signed 64-bit 2's-compliment integer GLint64 ------------- ------------------------------------ -------- ALCuint64SOFT Unsigned 64-bit integer GLuint64 New Procedures and Functions void alcGetInteger64vSOFT(ALCdevice *device, ALCenum pname, ALsizei size, ALCint64SOFT *values); New Tokens Accepted as the parameter of alcGetInteger64vSOFT: ALC_DEVICE_CLOCK_SOFT 0x1600 ALC_DEVICE_LATENCY_SOFT 0x1601 ALC_DEVICE_CLOCK_LATENCY_SOFT 0x1602 Accepted as the parameter of alGetSourcei64vSOFT: AL_SAMPLE_OFFSET_CLOCK_SOFT 0x1202 Accepted as the parameter of alGetSourcedvSOFT: AL_SEC_OFFSET_CLOCK_SOFT 0x1203 Additions to Specification Querying the Audio Device Clock Applications can query timing properties of the audio pipeline using the new 64-bit Integer query function, void alcGetInteger64vSOFT(ALCdevice *device, ALCenum pname, ALsizei size, ALCint64SOFT *values); This query function accepts all the same alcGetIntegerv queries, in addition to some new ones. Note that the size parameter is the number of ALCint64SOFT elements in the buffer provided, not the number of bytes. Table 6-x. 64-bit Integer Query Types. Name Description ---------------------------------- -------------------------------------- ALC_DEVICE_CLOCK_SOFT The audio device clock time, expressed in nanoseconds. NULL is an invalid device. ALC_DEVICE_LATENCY_SOFT The current audio device latency, in nanoseconds. This is effectively the delay for the samples rendered at the the device's current clock time from reaching the physical output. NULL is an invalid device. ALC_DEVICE_CLOCK_LATENCY_SOFT Expects a destination size of 2, and provides both the audio device clock time and latency, both in nanoseconds. The two values are measured atomically with respect to one another (i.e. the latency value was measured at the same time the device clock value was retrieved). NULL is an invalid device. If the ALC_SOFT_pause_device extension is available, the device clock does not increment while the device playback is paused. It is implementation- defined whether or not the device clock increments while no contexts are allocated. The initial clock time value of an opened device is also implementation-defined, except that it must not be negative and should be low enough to avoid wrapping during program execution. In addition to the above queries, an application can query the offset of a source with the device clock using two new source attributes. Source AL_SAMPLE_OFFSET_CLOCK_SOFT Attribute Name Signature Values Default --------------------------- --------- -------------------- ------- AL_SAMPLE_OFFSET_CLOCK_SOFT i64v {[0, Any], [0, Any]} N/A Description: the playback position, expressed in fixed-point samples, along with the device clock, expressed in nanoseconds. This attribute is read-only. The first value in the returned vector is the sample offset, which is a 32.32 fixed-point value. The whole number is stored in the upper 32 bits and the fractional component is in the lower 32 bits. The value is similar to that returned by AL_SAMPLE_OFFSET, just with more precision. The second value is the device clock, in nanoseconds. This updates at the same rate as the offset, and both are measured atomically with respect to one another. Source AL_SEC_OFFSET_LATENCY_SOFT Attribute Name Signature Values Default ------------------------ --------- ------------------------ ------- AL_SEC_OFFSET_CLOCK_SOFT dv {[0.0, Any], [0.0, Any]} N/A Description: the playback position, along with the device clock, both expressed in seconds. This attribute is read-only. The first value in the returned vector is the offset in seconds. The value is similar to that returned by AL_SEC_OFFSET, just with more precision. The second value is the device clock, in seconds. This updates at the same rate as the offset, and both are measured atomically with respect to one another. Be aware that this value may be subtly different from the other device clock queries due to the variable precision of floating-point values. Errors An ALC_INVALID_DEVICE error is generated if alcGetInteger64vSOFT is called with a NULL device and ALC_DEVICE_CLOCK_SOFT, ALC_DEVICE_LATENCY_SOFT, or ALC_DEVICE_CLOCK_LATENCY_SOFT queries. An AL_INVALID_OPEARTION error is generated if an attempt is made to set the AL_SAMPLE_OFFSET_CLOCK_SOFT or AL_SEC_OFFSET_CLOCK_SOFT source properties.