carb::audio::LoopPointDesc

Defined in carb/audio/IAudioPlayback.h

struct LoopPointDesc

descriptor of a loop point to set on a voice.

This may be specified both when a sound is first assigned to a voice in playSound() and to change the current loop point on the voice at a later time with setLoopPoint().

Public Members

const EventPoint *loopPoint = nullptr

the event point to loop at.

This may either be an explicitly constructed event point information block, or be one of the sound’s event points, particularly one that is flagged as a loop point. This will define a location to loop back to once the end of the initial play region is reached. This event point must be within the range of the sound’s data buffer. If the event point contains a zero length, the loop region will be taken to be the remainder of the sound starting from the loop point. This loop point will also contain a loop count. This loop count can be an explicit count or indicate that it should loop infinitely. Only a single loop point may be set for any given playing instance of a sound. Once the sound starts playing on a voice, the loop point and loop count may not be changed. A loop may be broken early by passing nullptr or an empty loop point descriptor to setLoopPoint() if needed. This may be nullptr to use one of the loop points from the sound itself by its index by specifying it in loopPointIndex.

When a loop point is specified explicitly in this manner, it will only be shallow copied into the voice object. If its string data is to be maintained to be passed through to a callback, it is the caller’s responsibility to ensure the original loop point object remains valid for the entire period the voice is playing. Otherwise, the string members of the loop point should be set to nullptr.

For performance reasons, it is important to ensure that streaming sounds do not have short loops (under 1 second is considered very short), since streaming loops will usually require seeking and some formats will need to partially decode blocks, which can require decoding thousands of frames in some formats.

size_t loopPointIndex = kLoopDescNoLoop

the index of the loop point to use from the sound data object itself.

This may be kLoopDescNoLoop to indicate that no loop point is necessary. This value is only used if loopPoint is nullptr. If the sound data object does not have a valid loop point at the specified index, the sound will still play but it will not loop. The loop point identified by this index must remain valid on the sound data object for the entire period that the voice is playing.

void *ext = nullptr

reserved for future expansion.

This must be set to nullptr.