carb::audio::EventPoint

struct EventPoint

a event point parsed from a data file.

This contains the ID of the event point, its name label (optional), and the frame in the stream at which it should occur.

Public Members

EventPointId id

the ID of the event point.

This is used to identify it in the file information but is not used internally except to match up labels or loop points to the event point.

size_t frame

the frame that the event point occurs at.

This is relative to the start of the stream for the sound. When updating event points with setEventPoints(), this can be set to kEventPointInvalidFrame to indicate that the event point with the ID id should be removed from the sound data object. Otherwise, this frame index must be within the bounds of the sound data object’s stream.

const char *label = nullptr

the user-friendly label given to this event point.

This may be parsed from a different information chunk in the file and will be matched up later based on the event point ID. This value is optional and may be nullptr.

const char *text = nullptr

optional text associated with this event point.

This may be additional information related to the event point’s position in the stream such as closed captioning text or a message of some sort. It is the host app’s responsibility to interpret and use this text appropriately. This text will always be UTF-8 encoded.

size_t length = 0

Length of the segment of audio referred to by this event point.

If length is non-zero, then length is the number of frames after frame that this event point refers to. If length is zero, then this event point refers to the segment from frame to the end of the sound. If loopCount is non-zero, then the region specified will refer to a looping region. If playIndex is non-zero, then the region can additionally specify the length of audio to play.

size_t loopCount = 0

Number of times this section of audio in the playlist should be played.

The region of audio to play in a loop is specified by length. if loopCount is 0, then this is a non-looping segment. If loopCount is set to kEventPointLoopInfinite, this specifies that this region should be looped infinitely.

size_t playIndex = 0

An optional method to specify an ordering for the event points or a subset of event points.

A value of 0 indicates that there is no intended ordering for this event point. The playlist indexes will always be a contiguous range starting from 1. If a user attempts to set a non-contiguous range of event point playlist indexes on a SoundData, the event point system will correct this and make the range contiguous.

UserData userData = {}

user data object attached to this event point.

This can have an optional destructor to clean up the user data object when the event point is removed, the user data object is replaced with a new one, or the sound data object containing the event point is destroyed. Note that when the user data pointer is replaced with a new one, it is the caller’s responsibility to ensure that an appropriate destructor is always paired with it.

void *ext = nullptr

reserved for future expansion.

This must be set to nullptr.