realtime.library Reference

Comprehensive function reference for realtime.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/realtime).

This page documents 10 functions of realtime.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

CreatePlayer()

CreatePlayerA -- create a player and link it to a conductor. (V37) CreatePlayer -- varargs stub for CreatePlayerA(). (V37)

Synopsis

player = CreatePlayerA(tagList); D0 A0

struct Player*CreatePlayerA(TagItem*);

player = CreatePlayer(firstTag, ...);

struct Player*CreatePlayer(Tag, ...);

Function

Creates a player structure with the desired attributes.

Inputs

tagList - pointer to an array of tags providing optional extra parameters, or NULL

Results

player - a pointer to a Player structure on success or NULL on failure. When NULL is returned, an error code can be returned in the longword variable pointed to by the optional PLAYER_ErrorCode tag.

See also

DeletePlayer(), GetPlayerAttrs(), SetPlayerAttrs()

DeletePlayer()

DeletePlayer -- delete a player. (V37)

Synopsis

DeletePlayer(player); A0

VOID DeletePlayer(struct Player*);

Function

Deletes the specified player.

Flushes the conductor that the player was connected to if this
is the last player connected to that conductor.

Inputs

player - Player structure to delete, as allocated by CreatePlayer(). May be NULL, in which case this function does nothing.

See also

CreatePlayer()

ExternalSync()

ExternalSync -- provide external source clock for a player's conductor. (V37)

Synopsis

result = ExternalSync(player, minTime, maxTime); D0 A0 D0 D1

BOOL ExternalSync(struct Player*, LONG, LONG);

Function

Allows external applications to constrain conductor time between minTime and maxTime, with the restraint that time can never run backwards. Does nothing if the given player is not the current External Sync source.

Inputs

player - player referencing the conductor to change minTime, maxTime - time constraints

Results

result - TRUE if everything went OK, FALSE if the player is not the current sync source or there is no conductor for the player.

FindConductor()

FindConductor -- find a conductor by name. (V37)

Synopsis

conductor = FindConductor(name); D0 A0

struct Conductor*FindConductor(STRPTR);

Function

Returns the conductor with the given name or NULL if not found.

The conductor list must be locked before calling this function. This
is done by calling LockRealTime(RT_CONDUCTORS).

Inputs

name - name of conductor to find.

Results

conductor - pointer to a Conductor structure, or NULL if not found.

See also

NextConductor(), LockRealTime(), UnlockRealTime()

GetPlayerAttrsA()

GetPlayerAttrsA -- get the attributes of a player. (V37) GetPlayerAttrs -- varargs stub for GetPlayerAttrsA(). (V37)

Synopsis

numProcessed = GetPlayerAttrsA(player, tagList); D0 A0 A1

ULONG GetPlayerAttrsA(struct Player*,TagItem*);

numProcessed = GetPlayerAttrs(player, firstTag, ...);

ULONG GetPlayerAttrs(struct Player*, Tag, ...);

Function

Retrieves the attributes of the specified player, according to the attributes chosen in the tag list. For each entry in the tag list, ti_Tag identifies the attribute, and ti_Data is a pointer to the longword variable where you wish the result to be stored.

Inputs

player - pointer to the player in question. May be NULL, in which case this function returns 0 tagList - pointer to TagItem list.

Results

numProcessed - the number of attributes successfully filled in.

See also

CreatePlayer(), SetPlayerAttrs()

LockRealTime()

LockRealTime -- prevent other tasks from changing internal structures. (V37)

Synopsis

lockHandle = LockRealTime(lockType); D0 D0

APTR LockRealTime(ULONG);

Function

This routine will lock the internal sempahores in the RealTime library. If they are already locked by another task, this routine will wait until they are free.

Inputs

lockType - the internal list to lock. Only RT_CONDUCTORS is currently defined.

Results

handle - if lockType is valid, returns a value that must be passed later to UnlockRealTime() to unlock the list. Returns NULL if passed an invalid lock type.

See also

UnlockRealTime()

NextConductor()

NextConductor -- return the next conductor on realtime.library's conductor list. (V37)

Synopsis

conductor = NextConductor(previousConductor); D0 A0

struct Conductor*NextConductor(struct Conductor*);

Function

Returns the next conductor on realtime.library's conductor list. If previousConductor is NULL, returns the first conductor in the list. Returns NULL if no more conductors.

The conductor list must be locked before calling this function. This
is done by calling LockRealTime(RT_CONDUCTORS).

Inputs

previousConductor - previous conductor or NULL to get first conductor.

Results

conductor - next conductor on the list, or NULL if no more.

See also

FindConductor(), LockRealTime(), UnlockRealTime()

SetConductorState()

SetConductorState -- change the play state of a player's conductor. (V37)

Synopsis

result = SetConductorState(player, state, time); D0 A0 D0 D1

LONG SetConductorState(struct Player*, ULONG, LONG);

Function

Changes the play state of the conductor referenced by the player. The states can be CONDSTATE_STOPPED, CONDSTATE_PAUSED, CONDSTATE_LOCATE, CONDSTATE_RUNNING, or the special value CONDSTATE_METRIC which asks the highest priority conducted node to do a CONDSTATE_LOCATE, or the special value CONDSTATE_SHUTTLE which informs the players that the clock value is changing, but the clock isn't actually running. Note that going from CONDSTATE_PAUSED to CONDSTATE_RUNNING does not reset the cdt_ClockTime of the conductor.

Inputs

player - player referencing the conductor to change state - new play state of conductor time - start time offset in realtime.library heartbeat units

Results

result - 0 if everything went OK, or a realtime.library error code if an error occured. These currently include RTE_PLAYING and RTE_NOCONDUCTOR.

SetPlayerAttrs()

SetPlayerAttrsA -- set the attributes of a player. (V37) SetPlayerAttrs -- varargs stub for SetPlayerAttrsA(). (V37)

Synopsis

result = SetPlayerAttrsA(player, tagList); D0 A0 A1

BOOL SetPlayerAttrsA(struct Player*,TagItem*);

result = SetPlayerAttrs(player,firstTag, ...);

BOOL SetPlayerAttrs(struct Player*, Tag, ...);

Function

Changes the attributes of the specified player, according to the attributes chosen in the tag list. If an attribute is not provided in the tag list, its value remains unchanged.

Inputs

player - player to set the attributes of. tagList - pointer to an array of tags specifying the attributes to change, or NULL.

Results

result - TRUE if all went well, FALSE if there was an error. When an error occurs, an error code can be returned in the longword variable pointed to by the optional PLAYER_ErrorCode tag.

See also

CreatePlayer(), DeletePlayer(), GetPlayerAttrs()

UnlockRealTime()

UnlockRealTime -- unlock internal lists. (V37)

Synopsis

UnlockRealTime(lockHandle); A0

VOID UnlockRealTime(APTR);

Function

Undoes the effects of LockRealTime().

Inputs

lockHandle - value returned by LockRealTime(). May be NULL.

See also

LockRealTime()