carb::audio::ContextParams2

struct ContextParams2

Extended context parameters descriptor object.

This provides additional context parameters that were not present in the original version of ContextParams. This structure also has room for future expansion.

Public Members

int64_t videoLatency = 0

An estimate of the current level of latency between when a video frame is produced and when it will be displayed to the screen.

In cases where a related renderer is buffering frames (ie: double or triple buffering frames in flight), there can be a latency build-up between when a video frame is displayed on screen and when sounds related to that particular image should start playing. This latency is related to the frame buffering count from the renderer and the current video frame rate. Since the video framerate can vary at runtime, this value could be updated frequently with new estimates based on the current video frame rate.

This value is measured in microseconds and is intended to be an estimate of the current latency level between video frame production and display. This will be used by the playback context to delay the start of new voices by approximately this amount of time. This should be used to allow the voices to be delayed until a time where it is more likely that a related video frame is visible on screen. If this is set to 0 (the default), all newly queued voices will be scheduled to start playing as soon as possible.

The carb::audio::estimateVideoLatency() helper function can be used to help calculate this latency estimate. Negative values are not allowed.

int64_t videoLatencyTrim = 0

An additional user specified video latency value that can be used to adjust the value specified in videoLatency by a constant amount.

This is expressed in microseconds. This could for example be exposed to user settings to allow user-level adjustment of audio/video sync or it could be a per-application tuned value to tweak audio/video sync. This defaults to 0 microseconds. Negative values are allowed if needed as long as videoLatency plus this value is still positive. The total latency will always be silently clamped to 0 as needed.

void *padding[32] = {}

Extra padding space reserved for future expansion.

Do not use this value directly. In future versions, new context parameters will be borrowed from this buffer and given proper names and types as needed. When this padding buffer is exhausted, a new ContextParams3 object will be added that can be chained to this one.

void *ext = nullptr

Reserved for future expansion.

This must be set to nullptr.