Common

Data Structures
struct	DmGuid
	Contains a 128-bit GUID (aka UUID) value. More...

Typedefs
typedef enum DmResult	DmResult
	Possible operation result values.
typedef struct DmGuid	DmGuid
	Contains a 128-bit GUID (aka UUID) value.
typedef void *	DmMemoryAlloc(void *ctx, size_t len)
	A malloc-like memory allocation function.
typedef void	DmMemoryFree(void *ctx, void *ptr)
	A free-like memory de-allocation function.
typedef uint32_t	DmRng(void *ctx)
	A rand_r-like random number generation function.
typedef enum DmLogLevel	DmLogLevel
	The set of message levels supported by the logging facilities.
typedef void	DmLogHandler(void *ctx, DmLogLevel lvl, char const *msg)

Enumerations
enum	DmResult {   DmResult_SUCCESS = 0 , DmResult_INVALID_ARGUMENT , DmResult_INVALID_STATE , DmResult_MEMORY_EXHAUSTED ,   DmResult_NOT_FOUND , DmResult_FILE_CORRUPT , DmResult_MUTEX_ERROR }
	Possible operation result values. More...
enum	DmLogLevel {   DmLogLevel_FATAL = 10 , DmLogLevel_ERROR = 20 , DmLogLevel_WARN = 30 , DmLogLevel_INFO = 40 ,   DmLogLevel_DEBUG = 50 , DmLogLevel_TRACE = 60 }
	The set of message levels supported by the logging facilities. More...

Functions
size_t	DmGuid_toString (DmGuid const *slf, char *out, size_t len)
	Convert the given GUID to a string.
DmResult	Dm_setHeapAllocator (DmMemoryAlloc *alloc, DmMemoryFree *free, void *ctx)
	Set the memory allocator to use internally.
void	Dm_setRandomNumberGenerator (DmRng *rng, void *ctx)
	Set the random number generator to use internally.
void	Dm_setLogger (DmLogLevel lvl, DmLogHandler *log, void *ctx)
	Set a callback to send log messages to.
void	Dm_setLoggerDefault (DmLogLevel lvl)
	Set a default logging function.
void	Dm_setLoggerLevel (DmLogLevel lvl)
	Set the log level of the library.

Detailed Description

Typedef Documentation

DmGuid

typedef struct DmGuid DmGuid

Contains a 128-bit GUID (aka UUID) value.

GUIDs are used in DirectMusic Segments, Styles, Bands and Downloadable Sound files as a way to uniquely identify distinct objects. For some of these objects, these GUIDs are exposed by their APIs. Many of these GUIDs could be manually set by the composer although generally, they are generated randomly by DirectMusic Producer upon object creation.

Attention

Do not alter GUIDs retrieved using the library APIs directly. Doing this can lead to cache misses which result in the underlying file being re-loaded the next time the object is used, causing higher memory usage and a spike in processing times. It can also result in broken playback (e.g. missing instruments).

See also

https://en.wikipedia.org/wiki/Universally_unique_identifier for more in-depth information about GUIDs.

DmLogHandler

typedef void DmLogHandler(void *ctx, DmLogLevel lvl, char const *msg)

Definition at line 196 of file dmusic.h.

DmMemoryAlloc

typedef void * DmMemoryAlloc(void *ctx, size_t len)

A malloc-like memory allocation function.

Allocates len bytes of contiguous memory and returns a pointer to the first byte allocated. May return NULL if memory allocation fails for any reason. In this case, function which relies on the allocation will fail with DmResult_MEMORY_EXHAUSTED to indicate memory allocation failure.

Warning

Functions implementing this interface are required to be thread-safe.

Parameters

ctx[in]	An arbitrary pointer provided when calling Dm_setHeapAllocator.
len[in]	The number of bytes to allocate.

Returns

A pointer to the first byte of the allocated memory block or NULL.

Return values

NULL	Memory allocation failed.

See also

Dm_setHeapAllocator Set the memory allocator for the library.

Definition at line 111 of file dmusic.h.

DmMemoryFree

typedef void DmMemoryFree(void *ctx, void *ptr)

A free-like memory de-allocation function.

De-allocates bytes starting a the memory location pointed to by ptr, which were previously allocated by calling a corresponding DmMemoryAlloc function. This function must not fail. If ptr is NULL, this function must be a no-op.

Warning

Functions implementing this interface are required to be thread-safe.

Parameters

ctx[in]	An arbitrary pointer provided when calling Dm_setHeapAllocator.
ptr[in]	A pointer to free, previously returned by the corresponding DmMemoryAlloc function or NULL.

See also

Dm_setHeapAllocator Set the memory allocator for the library.

Definition at line 125 of file dmusic.h.

DmRng

typedef uint32_t DmRng(void *ctx)

A rand_r-like random number generation function.

Generates a random number between 0 and UINT32_MAX. Functions implementing this interface must be thread-safe. The function is not required to produce different numbers upon invocation and it does not need to be cryptographically secure. Calling a function implementing this interface should be inexpensive.

Parameters

ctx[in]

An arbitrary pointer provided when calling Dm_setRandomNumberGenerator.

Returns

A random number between 0 and UINT32_MAX.

See also

Dm_setRandomNumberGenerator

Definition at line 157 of file dmusic.h.

Enumeration Type Documentation

DmLogLevel

enum DmLogLevel

The set of message levels supported by the logging facilities.

Enumerator
DmLogLevel_FATAL	The log message indicates a fatal error.
DmLogLevel_ERROR	The log message indicates an error.
DmLogLevel_WARN	The log message indicates a warning.
DmLogLevel_INFO	The log message is informational.
DmLogLevel_DEBUG	The log message is a debug message.
DmLogLevel_TRACE	The log message is a tracing message.

Definition at line 176 of file dmusic.h.

DmResult

enum DmResult

Possible operation result values.

Enumerator
DmResult_SUCCESS	The operation completed successfully.
DmResult_INVALID_ARGUMENT	An invalid argument was provided.
DmResult_INVALID_STATE	The operation could not be completed because the system is in an invalid state.
DmResult_MEMORY_EXHAUSTED	A memory allocation failed.
DmResult_NOT_FOUND	A resource was not found.
DmResult_FILE_CORRUPT	A resource file could not be parsed.
DmResult_MUTEX_ERROR	A mutex could not be locked.

Definition at line 46 of file dmusic.h.

Function Documentation

Dm_setHeapAllocator()

DmResult Dm_setHeapAllocator	(	DmMemoryAlloc *	alloc,
		DmMemoryFree *	free,
		void *	ctx
	)

Set the memory allocator to use internally.

This function should be called before calling any other library functions since, calling it after any allocation has been made internally will result in an error. It is guaranteed, however, that logging-related functions will never allocate.

Warning

This function is not thread safe.

Parameters

alloc[in]	A malloc-like function, which allocates memory. May not be NULL.
free[in]	A free-like function, which free memory previously allocated using alloc. May not be NULL.
ctx[in]	An arbitrary pointer passed to alloc and free on every invocation.

Returns

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

Return values

DmResult_INVALID_ARGUMENT	Either alloc or free was NULL.
DmResult_INVALID_STATE	The function was called after an allocation was already made.

See also

DmMemoryAlloc Allocation function definition.

DmMemoryFree De-allocation function definition.

Dm_setLogger()

void Dm_setLogger	(	DmLogLevel	lvl,
		DmLogHandler *	log,
		void *	ctx
	)

Set a callback to send log messages to.

Registers the given log function to be called whenever a log message is issued by the library. The given ctx pointer is passed alongside the log message on every invocation. If log is set to NULL, any existing log callback function is removed and logging is disabled.

Parameters

lvl	The log level to set for the library.
log[in]	The callback function to invoke whenever log message is generated or NULL
ctx[in]	An arbitrary pointer passed to log on every invocation.

See also

DmLogHandler Log callback function definition.

Dm_setLoggerLevel Function to set the log level on its own.

Dm_setLoggerDefault()

void Dm_setLoggerDefault

(

DmLogLevel

lvl

)

Set a default logging function.

Registers a default log handler which outputs all log messages at or above the given level to the standard error stream (stderr).

Parameters

lvl	The log level to set for the library.

See also

Dm_setLoggerLevel Function to set the log level on its own.

Dm_setLoggerLevel()

void Dm_setLoggerLevel

(

DmLogLevel

lvl

)

Set the log level of the library.

Parameters

lvl	The log level to set.

Dm_setRandomNumberGenerator()

void Dm_setRandomNumberGenerator	(	DmRng *	rng,
		void *	ctx
	)

Set the random number generator to use internally.

The given random number generator is sampled every time the library requires a random number. This includes but is not limited to:

• Selecting the next pattern to be played,
• selecting the next note/curve variation and
• applying random note offsets

Parameters

rng[in]	A pointer to a function to use as a random number generator or NULL to reset to the default random number generator.
ctx[in]	An arbitrary pointer passed to rng on every invocation.

See also

DmRng Requirements for the random number generator

DmGuid_toString()

size_t DmGuid_toString	(	DmGuid const *	slf,
		char *	out,
		size_t	len
	)

Convert the given GUID to a string.

The output string is generated in 8-4-4-4-12 format and thus needs 36 chars (excl. nul-terminator) to be fully converted. The number of chars actually converted can be obtained from the return value.

Parameters

slf[in]	The GUID to convert to a string.
out[out]	The output buffer to write the chars to.
len	The maximum number of bytes available in the out buffer.

Returns

The number of chars actually written to the out buffer.