TODO. More...

Typedefs
typedef struct DmPerformance	DmPerformance
	Represents a DirectMusic Performance.

typedef enum DmRenderOptions	DmRenderOptions

typedef enum DmTiming	DmTiming

typedef enum DmEmbellishmentType	DmEmbellishmentType
	Embellishment types for choosing transition patterns.

Enumerations
enum	DmRenderOptions { DmRender_SHORT = 1 << 0 , DmRender_FLOAT = 1 << 1 , DmRender_STEREO = 1 << 2 }

enum	DmTiming { DmTiming_INSTANT = 1 , DmTiming_GRID = 2 , DmTiming_BEAT = 3 , DmTiming_MEASURE = 4 }

enum	DmEmbellishmentType { DmEmbellishment_NONE = 0 , DmEmbellishment_GROOVE = 1 , DmEmbellishment_FILL = 2 , DmEmbellishment_INTRO = 3 , DmEmbellishment_BREAK = 4 , DmEmbellishment_END = 5 , DmEmbellishment_END_AND_INTRO = 6 }
	Embellishment types for choosing transition patterns. More...

Functions
DmResult	DmPerformance_create (DmPerformance **slf, uint32_t rate)
	Create a new DirectMusic Performance object.

DmPerformance *	DmPerformance_retain (DmPerformance *slf)
	Add one to the reference count of a performance.

void	DmPerformance_release (DmPerformance *slf)
	Subtract one from the reference count of a performance.

DmResult	DmPerformance_playSegment (DmPerformance slf, DmSegment sgt, DmTiming timing)
	Schedule a new segment to be played by the given performance.

DmResult	DmPerformance_playTransition (DmPerformance slf, DmSegment sgt, DmEmbellishmentType embellishment, DmTiming timing)
	Schedule a new segment to play by the given performance with a transition.

DmResult	DmPerformance_renderPcm (DmPerformance slf, void buf, size_t num, DmRenderOptions opts)
	Render a given number of PCM samples from a performance.

void	DmPerformance_setVolume (DmPerformance *slf, float vol)
	Set the playback volume of a performance.

Detailed Description

TODO.

Typedef Documentation

◆ DmPerformance

typedef struct DmPerformance DmPerformance

Represents a DirectMusic Performance.

Definition at line 300 of file dmusic.h.

Enumeration Type Documentation

◆ DmEmbellishmentType

enum DmEmbellishmentType

Embellishment types for choosing transition patterns.

Enumerator
DmEmbellishment_NONE	Don't choose a pattern.
DmEmbellishment_GROOVE	Only choose patterns with the default 'groove' embellishment.
DmEmbellishment_FILL	Only choose patterns with the 'fill' embellishment.
DmEmbellishment_INTRO	Only choose patterns with the 'intro' embellishment.
DmEmbellishment_BREAK	Only choose patterns with the 'break' embellishment.
DmEmbellishment_END	Only choose patterns with the 'end' embellishment.
DmEmbellishment_END_AND_INTRO	Choose two patterns, one with the 'end' embellishment from the playing segment and one with the 'intro' embellishment from the new segment and play them back-to-back. Todo: This is not yet implemented.

Definition at line 488 of file dmusic.h.

◆ DmRenderOptions

enum DmRenderOptions

Enumerator
DmRender_SHORT	Render format flag to request rendering of `int16_t` samples.
DmRender_FLOAT	Render format flag to request rendering of `float` samples.
DmRender_STEREO	Render flags to request stereo PCM rendering.

Definition at line 462 of file dmusic.h.

◆ DmTiming

enum DmTiming

Enumerator
DmTiming_INSTANT	Timing flag indicating start at the next possible tick.
DmTiming_GRID	Timing flag indicating start at the next possible grid boundary.
DmTiming_BEAT	Timing flag indicating start at the next possible beat boundary.
DmTiming_MEASURE	Timing flag indicating start at the next possible measure boundary.

Definition at line 473 of file dmusic.h.

Function Documentation

◆ DmPerformance_create()

DmResult DmPerformance_create	(	DmPerformance **	slf,
		uint32_t	rate
	)

Create a new DirectMusic Performance object.

Parameters

slf[out]	A pointer to a variable in which to store the newly created performance.
rate	The sample rate for the synthesizer. Provide 0 to use the default (44100 Hz).

Returns: DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	`slf` was `NULL`.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.

◆ DmPerformance_playSegment()

DmResult DmPerformance_playSegment	(	DmPerformance *	slf,
		DmSegment *	sgt,
		DmTiming	timing
	)

Schedule a new segment to be played by the given performance.

The segment is played at the next timing boundary provided with timing. This function simply stops the currently playing segment and starts playing the next one. To play a transition between the two segments, use DmPerformance_playTransition.

Note: The segment will always start playing strictly after the last call to DmPerformance_renderPcm since that function advances the internal clock. This means, if you have already rendered ten seconds worth of PCM using DmPerformance_renderPcm, the transition can only audibly be heard after these ten seconds of PCM have been played.

Parameters

slf[in]	The performance to play the segment in.
sgt[in]	The segment to play or `NULL` to simply stop the playing segment.
timing	The timing bounding to start playing the segment at.

Returns: DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	`slf` was `NULL`.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.
DmResult_MUTEX_ERROR	An error occurred while trying to lock an internal mutex.

See also: DmPerformance_playTransition

◆ DmPerformance_playTransition()

DmResult DmPerformance_playTransition	(	DmPerformance *	slf,
		DmSegment *	sgt,
		DmEmbellishmentType	embellishment,
		DmTiming	timing
	)

Schedule a new segment to play by the given performance with a transition.

Schedules a new transitional segment to be played, which first plays a transitional pattern from the currently playing segment's style and then starts playing the given segment. This can be used to smoothly transition from one segment to another.

The transitional pattern is selected by its embellishment type provided when calling the function. Only embellishments matching the current groove level are considered.

Note: The DmEmbellishment_END_AND_INTRO embellishment is currently not implemented.

Parameters

slf[in]	The performance to play the transition in.
sgt[in]	The segment to transition to or `NULL` to transition to silence.
embellishment	The embellishment type to use for the transition.
timing	The timing bounding to start playing the transition at.

Returns: DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	`slf` or `sgt` was `NULL`.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.
DmResult_MUTEX_ERROR	An error occurred while trying to lock an internal mutex.

See also: DmPerformance_playSegment

◆ DmPerformance_release()

void DmPerformance_release ( DmPerformance * slf )

Subtract one from the reference count of a performance.

If a call to this function reduces the reference count to zero, it also de-allocates the performance and releases any resources referenced by it.

Parameters

slf[in] The performance to release.

◆ DmPerformance_renderPcm()

DmResult DmPerformance_renderPcm	(	DmPerformance *	slf,
		void *	buf,
		size_t	num,
		DmRenderOptions	opts
	)

Render a given number of PCM samples from a performance.

Since the performance is played "on demand", calling this function will advance the internal clock and perform all musical operation for the rendered timeframe. If no segment is currently playing, the output will be set to zero samples.

Using the opts parameter, you can control what data is output. The DmRender_SHORT and DmRender_FLOAT bits indicate the format of the PCM data to output (either as int16_t or 32-bit float). All data is output as host-endian. Setting the DmRender_STEREO bit renders interleaved stereo samples.

Warning: When rendering stereo audio, you must provide an output array with an even number of elements!

Parameters

slf[in]	The performance to render from.
buf[out]	A buffer to render PCM into.
num	The number of elements available in `buf`. This will be equal to the number of samples when rendering mono PCM or 2 time the number of samples when rendering stereo.
opts	A bitfield with options for the renderer.

Returns: DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	`slf` or `buf` was `NULL`, `opts` included multiple format specifiers or `opts` included DmRender_STEREO and `num` was not even.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.
DmResult_MUTEX_ERROR	An error occurred while trying to lock an internal mutex.

◆ DmPerformance_retain()

DmPerformance * DmPerformance_retain ( DmPerformance * slf )

Add one to the reference count of a performance.

Parameters

slf[in] The performance to retain.

Returns: The same performance as was given in slf or NULL if slf was NULL.

◆ DmPerformance_setVolume()

void DmPerformance_setVolume	(	DmPerformance *	slf,
		float	vol
	)

Set the playback volume of a performance.

Note: This only affects the output created when calling DmPerformance_renderPcm.

Parameters

slf[in]	The performance to set the volume of.
vol	The new volume to set (between 0 and 1).

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ DmPerformance

Enumeration Type Documentation

◆ DmEmbellishmentType

◆ DmRenderOptions

◆ DmTiming

Function Documentation

◆ DmPerformance_create()

◆ DmPerformance_playSegment()

◆ DmPerformance_playTransition()

◆ DmPerformance_release()

◆ DmPerformance_renderPcm()

◆ DmPerformance_retain()

◆ DmPerformance_setVolume()