Chapter 9. DM Processing

The DM library is concerned with two types of interfaces: Paths for digital media through jacks into and out of the machine, and pipes for digital media to and from transcoders. Both share common control, buffer, and queueing mechanisms. These mechanisms are first described in the context of a complete program example. Subsequently, the individual functions are presented.

DM Program Structure

DM programs are composed of the following structure. Each of the functions are described later in this chapter (except where noted).

// get list of available dmedia devices
dmGetCapabilities( systemid,  );

// search the devices to find the desired jack, path, or xcode to open
	// (See Chapter 7: DM Capabilities for function description)
dmGetCapabilities( deviceid, & capabilities  );

	// query the jack, path, or xcode to discover allowable open options and parameters
	// (See Chapter 7: DM Capabilities for function description)
dmGetCapabilities( objectid, & capabilities  );
	// query for individual parameter characteristics
	// (See Chapter 7: DM Capabilities for function description)
dmPvGetCapabilities( deviceid,& capabilities  );

// free memory associated with any of the above get capabilities:
	// (See Chapter 7: DM Capabilities for function description)
dmFreeCapabilities( capabilities );

	// open a logical connection todmhe desired object
dmOpen( objectId, options,  );

	// get and set any necessary immediate controls
dmGetControls( openid, controls );
dmSetControls( openid, controls );

	// send any synchronous controls
dmSendControls( openid, controls );

// pre-roll buffers
dmSendBuffers( openid, buffers );

	// prepare for asynchronous processing by getting a wait handle
dmGetWaitHandle( openid,  );

	// start the path or xcode transferring
dmBeginTransfer( openid );

// perform synchronous work
dmXcodeWork( openid );

// check on the status of the queues
dmGetSendMessageCount( openid,  );
dmGetReceiveMessageCount( openid,  );

// process return messages
dmReceiveMessage( openid,  );

// find specific returned parameters
dmPvFind( msg, param );

// repeat dmSendControls, dmSendBuffers, dmXcodeWork, etc. as required

// stop the transfer
dmEndTransfer( openid );

// close the logical connection
dmClose( openid );

// other useful functions:
dmGetVersion( ,  );
dmGetSystemUST( systemId,  );
dmStatusName( status );
dmMessageName( messageType );

DMstatus Return Value

Note that all DM API functions return an DMstatus value. This provides a consistent error checking interface. (Certain “Convenience Functions” do not adhere to this standard.) See descriptions below. The various DMstatus return values are:

DM_STATUS_NO_ERROR

The operation succeeded without error.

DM_STATUS_NO_OPERATION

The function resulted in no operation.

DM_STATUS_OUT_OF_MEMORY

The operation was aborted due to lack of memory resources.

DM_STATUS_INVALID_ID

One of the arguments representing an ID is invalid.

DM_STATUS_INVALID_ARGUMENT

One of the arguments in the function call is invalid.

DM_STATUS_INVALID_VALUE

The value of a parameter is invalid.

DM_STATUS_INVALID_PARAMETER

The specified parameter (“param” field) is invalid for the requested operation.

DM_STATUS_INVALID_CONFIGURATION

Since control messages may be incomplete, and each individual set or send controls may be valid, there exists a point in time where the processing of buffers must be accomplished using those aggregate controls. If for some reason, the “combination of controls” is invalid, the processing is aborted and the DM_STATUS_INVALID_CONFIGURATION error (for dmSetControls) or the event (for dmSendControls) is returned

DM_STATUS_RECEIVE_QUEUE_EMPTY

The receive queue was empty when an dmReceiveMessage function was processed.

DM_STATUS_SEND_QUEUE_OVERFLOW

Too many dmSendControls and/or dmSendBuffers have been issued.

DM_STATUS_RECEIVE_QUEUE_OVERFLOW

The receive queue will not accept the return message if the current message is enqueued on the send queue.

DM_STATUS_INSUFFICIENT_RESOURCES

Not all the resources required to complete the operation are available.

DM_STATUS_DEVICE_UNAVAILABLE

The requested device has become unavailable, possibly by being powered down or removed from the system.

DM_STATUS_ACCESS_DENIED

The requested open access conflicts with a previous access already established or the requested parameter cannot be modified during the current operation mode.

DM_STATUS_INTERNAL_ERROR

An operation was aborted due to a system or device I/O error.

Device States

For audio and video paths and transcoders, the device transitions through well-known states, known as Device States. These states are listed below:

DM_DEVICE_STATE_READY

Indicates that the device is in a quiescent state and can accept messages, but will not process them until it enters the DM_DEVICE_STATE_TRANSFERRING state.

DM_DEVICE_STATE_TRANSFERRING

Indicates that the device has accepted a dmBeginTRansfer and is now processing messages.

DM_DEVICE_STATE_WAITING

Indicates that the device is currently waiting for an external event such as the DM_WAIT_FOR_AUDIO_MSC_INT64 predicate control. Messages may still be enqueued, but will not be processed until the wait condition is removed.

DM_DEVICE_STATE_ABORTING

Indicates that the device has terminated message processing, usually by accepting a dmEndTransfer. All messages remaining on the input queue will be flushed to the output queue with the message type indicating that the message was aborted. (DM_CONTROLS_ABORTED, DM_QUERY_CONTROLS_ABORTED, and DM_BUFFERS_ABORTED.)

DM_DEVICE_STATE_FINISHING

Indicates that the device is terminating the transfer, but will complete processing of the remaining messages in the input queue.

Opening a Jack, Path or Xcode

In order to communicate with a Jack, Path, or Xcode, a connection must be opened. A physical device (e.g. a PCI card) may simultaneously support several such connections. These connections are done by calling dmOpen:

DMstatus dmOpen (const DMint64 objectId, DMpv* options,DDMopenid* openid);

objectId is the 64-bit unique identifier for the object (jack, path or transcoder) to be opened. The parameters in options specify the initial configuration of the device to be opened. These parameters are described in Table 10.1, where the string in the Parameter column is a shortened form of the full parameter name. The full parameter name is of the form DM_parameter_type, where parameter and type are the strings listed in the Parameter and Type columns respectively. For example, the full parameter name of OPEN_MODE is DM_OPEN_MODE_INT32.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The call succeeded and the handle of the open instance of the object has been returned in openid.

DM_STATUS_INVALID_ID

The argument objectid is invalid.

DM_STATUS_INVALID_ARGUMENT

One of the arguments is otherwise invalid.

DM_STATUS_INVALID_PARAMETER

One of the parameters in the options list is invalid.

DM_STATUS_INVALID_VALUE

One of the parameters in the options list has an invalid value.

DM_STATUS_OUT_OF_MEMORY

Insufficient memory is available to perform the operation, including the space needed to allocate the queues for messages between the application and the device.

DM_STATUS_INSUFFICIENT_RESOURCES

Some other required resource is not available, possibly by being already in use by this or another application.

DM_STATUS_DEVICE_UNAVAILABLE

The requested device has gone off-line, possibly by being disconnected.

DM_STATUS_ACCESS_DENIED

The requested open access mode is not available.

DM_STATUS_INTERNAL_ERROR

An operating system error has occurred.

Jack Open Parameters

The following open parameters are supported when opening a jack.

Table 9-1. Jack, dmOpen Options

Parameter

Type

Description

OPEN_MODE

INT32

Application's intended use for the device. Defined values are:

DM_MODE_RO for read only access. DM_MODE_RWS for shared read/write access. DM_MODE_RWE for exclusive access.

The default is defined by the device's capabilities.

OPEN

_RECEIVE

_QUEUE_COUNT

INT32

Applications' preferred size (number of messages) for the receive queue. This influences the amount of memory allocated for this queue when the device is opened. Default is device-dependent A null value indicates that the application does not expect to receive any events from the jack.

OPEN

_EVENT

_PAYLOAD_COUNT

INT32

Application's preferred size (number of messages) for the queue event payload area. This payload area holds the contents of event messages on the receive queue. Default is device dependent. A null value indicates that the application does not expect to receive any events from the jack.


The DM_OPEN_OPTION_IDS returned by a dmGetCapabilities call using the JACK ID, returns a list of these parameters. dmPvGetCapabilities can then be used to discover allowable values.

Path Open Parameters

The following open parameters are supported when opening a path: The DM_OPEN_OPTION_IDS

Table 9-2. dmOpen Options

Parameter

Type

Description

OPEN_MODE

INT32

Application's intended use for the device. Defined values are:

DM_MODE_RO for read only access DM_MODE_RWS for shared read/write access DM_MODE_RWE for exclusive access.

The default is defined by the device's capabilities.

OPEN

_SEND

_QUEUE_COUNT

INT32

Application's preferred size (number of messages) for the send queue. This influences the amount of memory allocated for this queue when the device is opened. Default is device-dependent.

OPEN

_RECEIVE

_QUEUE_COUNT

INT32

Applications' preferred size (number of messages) for the receive queue. This influences the amount of memory allocated for this queue when the device is opened. Default is device-dependent

OPEN

_MESSAGE

_PAYLOAD_SIZE

INT32

Application's preferred size (in bytes) for the queue message payload area. The payload area holds messages on both the send and receive queues. Default is device-dependent.

OPEN

_EVENT

_PAYLOAD_COUNT

INT32

Application's preferred size (number of messages) for the queue event payload area. This payload area holds the contents of event messages on the receive queue. Default is device-dependent.

OPEN

_SEND

_SIGNAL_COUNT

INT32

Application's preferred low-water level (number of empty message slots) in the send queue. When the device dequeues a message and causes the number of empty slots to exceed this level, then the device will signal the send queue event. Default is device-dependent.


Xcode Open Parameters

Table 9-3. dmOpen Options

Parameter

Type

Description

OPEN_MODE

INT32

Application's intended use for the device. Defined values are:

DM_MODE_RO for read only access DM_MODE_RWS for shared read/write access DM_MODE_RWE for exclusive access.

The default is defined by the device's capabilities.

OPEN

_SEND

_QUEUE_COUNT

INT32

Application's preferred size (number of messages) for the send queue. This influences the amount of memory allocated for this queue when the device is opened. Default is device-dependent.

OPEN

_RECEIVE

_QUEUE_COUNT

INT32

Applications' preferred size (number of messages) for the receive queue. This influences the amount of memory allocated for this queue when the device is opened. Default is device-dependent

OPEN

_MESSAGE

_PAYLOAD_SIZE

INT32

Application's preferred size (in bytes) for the queue message payload area. The payload area holds messages on both the send and receive queues. Default is device-dependent.

OPEN

_EVENT

_PAYLOAD_COUNT

INT32

Application's preferred size (number of messages) for the queue event payload area. This payload area holds the contents of event messages on the receive queue. Default is device-dependent.

OPEN

_SEND

_SIGNAL_COUNT

INT32

Application's preferred low-water level (number of empty message slots) in the send queue. When the device dequeues a message and causes the number of empty slots to exceed this level, then the device will signal the send queue event. Default is device-dependent.

OPEN_XCODE_MODE

INT32

Application's preferred mode for controlling a software transcoder. This parameter does not apply to paths.

Defined values are:

DM_XCODE_MODE_SYNCHRONOUS when processing by a software transcoder is to be initiated by the application.

DM_XCODE_MODE_AYNCHRONOUS when processing by a software transcoder is to be initiated by DM.

Default is DM_XCODE_MODE_ASYNCHRONOUS.

OPEN_XCODE_STREAM

INT32

Selects between single and multi-stream transcoders. In single stream mode, source and destination buffers are processed at the same rate.

In multi-stream mode, the source and destination pipes each have their own queue of buffers and may run at different rates (this is more complicated to program, but may be more efficient for some intra-frame codecs). Defined values are:

DM_XCODE_STREAM_SINGLE DM_XCODE_STREAM_MULTI

Default is DM_XCODE_STREAM_SINGLE

In a future release, DM_XCODE_STREAM_MULTI transcoders will be supported.


Set Controls

Some controls on a logical connection are “asynchronous” in nature and do not affect an ongoing data transfer. These controls may be set in an “out of band” message using the dmSetControls operation:

DMstatus dmSetControls( DMopenid openid, DMpv* controls );

openid is the 64-bit unique identifier returned by the dmOpen function. The controls parameter is a message containing various parameters as described elsewhere in this document. Note that this call blocks until the device has processed the message. To identify an invalid value specification, the device will set the length component of the erroneous DMpv to -1, otherwise the controls array will not be altered in any way and may be reused. The controls message is not enqueued on the send queue but instead is sent directly to the device. The device will attempt to process the message "as soon as possible".

Enqueueing entails a copy operation,

NOTES

This call returns as soon as the control array has been processed. This does not mean that buffers have been affected by the parameter change. Rather, it means that the parameters have been validated and sent to the device (i.e. in most cases this means that they reside in registers).

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The control values were set successfully.

DM_STATUS_INVALID_ID

The specified openid is invalid.

DM_STATUS_INVALID_PARAMETER

At least one of the parameters in the controls array was not recognized (the first such offending control will be marked with length -1, remaining controls will be skipped and the entire message will be ignored).

DM_STATUS_INVALID_VALUE

At least one of the parameters in the controls array has a value which is invalid. This may be because the parameter value is outside the legal range, or it may be that parameter value is inconsistent (the entire message will be ignored and the system will attempt to flag the first offending value by setting the length to -1).

Get Controls

Control on a logical connection may be queried asynchronously to an ongoing transfer:

DMstatus dmGetControls (DMopenid openid, DMpv* controls);

openid is the identifier, returned by dmOpen, of the jack, path, or transcoder whose parameters are to be queried. The controls parameter is a message consisting of parameters to be queried. The device will place its reply in the controls array argument (overwriting existing values). Control values that were obtained successfully will have non-negative lengths. GetControls returns the state of the controls at the time the call is made. If GetControls is called before a control has been explicitly set, then generally the returned value is undefined (exceptions are noted in the definitions the controls, see DM_UST).

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR The control values were obtained successfully.

DM_STATUS_INVALID_ID The specified open device id is invalid.

DM_STATUS_INVALID_PARAMETER At least one of the parameters in the controls array was not recognized (the offending control will be marked with length -1; remaining controls will still be processed).

DM_STATUS_INVALID_VALUE At least one of the parameters in the controls array has a value which is invalid (the offending control will be marked with length -1; remaining controls will still be processed).

Send Controls

Other controls on a logical connection are “synchronous” in nature and do affect the processing of subsequent data buffers. These controls should be set in an “in band” message using the dmSendControls operation:

DMstatus dmSendControls( DMopenid openid, DMpv* controls );

openid is the 64-bit unique identifier returned by the dmOpen function. The controls parameter is a message containing various parameters as described in the preceding chapters.

The dmSendControls sends a message containing a list of control parameters to a previously-opened digital media device. These controls are enqueued on the send queue in sequence with any other messages to that device. Any control changes are thus guaranteed not to have any effect until all previously enqueued messages have been processed.

This call returns as soon as the control change has been enqueued to the device. It does not wait until the control change has actually taken effect.

All the control changes within a single message are considered occur atomically. If any one control change in the message fails, then the entire message has no effect. A successful return does not guarantee that resources will be available to support the requested control change at the time it is processed by the device.

As each message is processed by the device, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the requested controls. Note that a device may take an arbitrarily long time to generate a reply (it may, for example, wait for several messages before replying to the first). If an application requires an immediate response, consider using the set controls operation instead.

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates the control change has not been enqueued and will thus have no effect.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The control values were set successfully.

DM_STATUS_INVALID_ID

The specified openid is invalid.

DM_STATUS_SEND_QUEUE_OVERFLOW

There was not enough space on the path send queue for this latest message. Try again later after the device has had time to catch up, or specify a larger send queue size on open.

DM_STATUS_RECEIVE_QUEUE_OVERFLOW

There is not currently enough space on the receive queue to hold the reply to this message. Read some replies from the receive queue and then try to send again, or specify a larger receive queue size on open.

DM_STATUS_INVALID_PARAMETER

At least one of the parameters in the controls array was not recognized (the first such offending control will be marked with length -1, remaining controls will be skipped and the entire message will be ignored).

DM_STATUS_INVALID_VALUE

At least one of the parameters in the controls array has a value which is invalid. This may be because the parameter value is outside the legal range, or it may be that parameter value is inconsistent (the entire message will be ignored and the system will attempt to flag the first offending value by setting the length to -1).

RETURN EVENT

The event returned from processing a dmSendControls may be one of the following:

DM_CONTROLS_COMPLETE

The controls were processed without error.

DM_CONTROLS_ABORTED

The processing of the controls were aborted due to another asynchronous event, such as the dmEndTransfer function was requested.

DM_CONTROLS_FAILED

The processing of the controls failed because the values were not accepted at the time of processing.

Send Buffers

This function sends a message containing a list of buffers to a previously-opened digital media device. These buffers are enqueued on the send queue in sequence with any other messages to that device. All the buffers within a single message are considered to apply to the same point in time. For example, a single buffers message could contain image, audio, HANC and VANC buffers, each specified with its own buffer parameter in the buffers message.

DMstatus dmSendBuffers( DMopenid openid, DMpv* buffers );

openid refers to a previously-opened logical connection as returned from dmOpen, while buffers is a message containing a list of buffer parameters.

As each message is processed by the path, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the buffers.

A successful return value from the dmSendBuffers guarantees only that the requested buffers have been enqueued to the device. Any error return value indicates the buffers have not been enqueued and will thus have no effect.

The memory for the buffers is designated by the POINTER value, and is always owned by the application. However, after a buffer has been sent, it is on loan to the system and must not be touched by the application. After the buffer has been returned via ReceiveMessage, then the application is again free to delete and/or modify it.

When sending a buffer to be output, the application must set the buffer length to indicate the number of valid bytes in the buffer. In this case maxLength is ignored by the device (it doesn't matter how much larger the buffer may be, since the device won't read past the last valid byte).

When sending a buffer to be filled (on input) the application must set the buffer maxLength to indicate the maximum number of bytes which may be written by the device to the buffer. As the device processes the buffer, it will write no more than the maxLength bytes and then set the returned length to indicate the last byte written. The maxLength is returned without change. It is acceptable to send the same buffer multiple times.

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates that the buffer has not been enqueued and will thus have no effect.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The buffers message was enqueued successfully.

DM_STATUS_INVALID_ID

The specified openid is invalid.

DM_STATUS_SEND_QUEUE_OVERFLOW

There was not enough space on the path send queue for this latest message. Try again later after the device has had time to catch up, or specify a larger send queue size on open.

DM_STATUS_RECEIVE_QUEUE_OVERFLOW

There is not currently enough space on the receive queue to hold the reply to this message. Read some replies from the receive queue and then try to send again, or specify a larger receive queue size on open.

DM_STATUS_INVALID_PARAMETER

At least one of the parameters in the message was not recognized (the first such offending control will be marked with length -1, remaining controls will be skipped and the entire message will be ignored).

DM_STATUS_INVALID_VALUE

At least one of the parameters in the message has a value which is invalid. This may be because the parameter value is outside the legal range, or it may be that parameter value is inconsistent (the entire message will be ignored and the system will attempt to flag the first offending value by setting the length to -1).

RETURN EVENT

The event returned from processing a dmSendControls may be one of the following:

DM_BUFFERS_COMPLETE

The buffers were processed without error.

DM_BUFFERS_ABORTED

The processing of the buffers was aborted due to another asynchronous event, such as the dmEndTransfer function was requested.

DM_BUFFERS_FAILED

The processing of the buffers failed because the values were not accepted at the time of processing. This can occur both because parameters in the buffers message were invalid or due to the current control settings at the time of processing (because of previous dmSendControls messages), the processing of buffers would be invalid. Since preceding control messages may be incomplete, and each of the individual set or send controls may be valid, there still exists a point in time where the processing of buffers must be accomplished using those aggregate controls. If for some reason, the “combination of controls” is invalid, the processing is aborted and the event DM_BUFFERS_FAILED is returned.

Query Controls

To obtain the control values on a logical connection that are synchronous via an “in band” message, use the dmQueryControls operation:

DMstatus dmQueryControls( DMopenid openid, DMpv* controls );

openid is the 64-bit unique identifier returned by the dmOpen function. The controls parameter is a message containing various parameters as described in the preceding chapters.

The dmQueryControls sends a message containing a list of control parameters to a previously-opened digital media device. These controls are enqueued on the send queue in sequence with any other messages to that device. The control values returned are thus guaranteed to reflect any and all previously enqueued dmSendControls messages that have been processed.

This call returns as soon as the message has been enqueued to the device. It does not wait until the control value is available.

As each message is processed by the device, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the requested controls. Note that a device may take an arbitrarily long time to generate a reply (it may, for example, wait for several messages before replying to the first). If an application requires an immediate response, consider using the get controls operation instead.

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates the control change has not been enqueued and will thus have no effect.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The control values were set successfully.

DM_STATUS_INVALID_ID

The specified openid is invalid.

DM_STATUS_SEND_QUEUE_OVERFLOW

There was not enough space on the path send queue for this latest message. Try again later after the device has had time to catch up, or specify a larger send queue size on open.

DM_STATUS_RECEIVE_QUEUE_OVERFLOW

There is not currently enough space on the receive queue to hold the reply to this message. Read some replies from the receive queue and then try to send again, or specify a larger receive queue size on open.

DM_STATUS_INVALID_PARAMETER

At least one of the parameters in the controls array was not recognized (the first such offending control will be marked with length -1, remaining controls will be skipped and the entire message will be ignored).

RETURN EVENT

The event returned from processing a dmQueryControls may be one of the following:

DM_QUERY_CONTROLS_COMPLETE

The query controls were processed without error.

DM_QUERY_CONTROLS_ABORTED

The processing of the query controls were aborted due to another asynchronous event, such as the dmEndTransfer function was requested.

Get Wait Handle

When processing a number of digital media streams asynchronously, there exists a need for the application to know when processing is required on each individual stream. The dmGetSendWaitHandle and dmGetReceiveWaitHandle functions are provided to facilitate this processing:

DMstatus dmGetSendWaitHandle( DMopenid openid, DMwaitable* WaitHandle );
DMstatus dmGetReceiveWaitHandle( DMopenid openid, DMwaitable* WaitHandle );

The openid is a previously-opened digital media object as returned by a dmOpen call and the WaitHandle is the requested returned wait handle. This function returns an event handle on which an application may wait. On IRIX, UNIX and Linux, DMwaitable is a file descriptor for use in select(). On Windows, DMwaitable is a HANDLE which may be used in the win32 functions WaitForSingleDevice or WaitForMultipleDevices.

The send queue handle is signaled whenever the device dequeues a message and the message count drops below a preset level (set by the parameter DM_OPEN_SEND_SIGNAL_COUNT specified when the object was opened). Thus, if the send queue is full, an application may wait on this handle for notification that space is available for additional messages.

The receive queue handle is signaled whenever the device enqueues a reply message. Thus, if the receive queue is empty, the application may wait on this handle for notification that additional reply messages are ready.

The returned handles were created when the device was opened and are automatically destroyed when the path is closed.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The wait handle was obtained successfully.

DM_STATUS_INVALID_ID

The specified open device handle is invalid.

Begin Transfer

dmBeginTransfer starts the actual transferring of buffers to the logical media connection:

DMstatus dmBeginTransfer (DMopen id openid);

The openid is a previously-opened digital media object as returned by an dmOpen call.

This function begins a continuous transfer on the specified Path or Xcode. It is not used on a logical connection to a Jack. This call advises the device to begin processing buffers and returning messages to the application. As stated earlier, sending a buffer to a device that has not yet begun transfers will cause the send queue to stall until the transfers have started. Typically applications will open a device, send several buffers and then call dmBeginTransfer. This call returns as soon as the device has begun processing transfers. It does not block until the first buffer has been processed. It is an error to call this function more than once without an intervening call to dmEndTransfer.

NOTES

The delay between a call to dmBeginTransfer and the transfer of the first buffer is implementation-dependent. To begin sending data at a particular time, an application should start the transfer early (enqueueing blank buffers) and use the UST/MSC mechanism to synchronize the start of real data.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The device agreed to begin transfer on the path.

DM_STATUS_INVALID_ID

The specified open device id is invalid.

DM_STATUS_NO_OPERATION

The call had no effect (transfers have already been started).

XCode Work

For software-only transcoders opened with the DM_XCODE_MODE_INT32 open option set to DM_XCODE_MODE_SYNCHRONOUS, this function allows an application to control exactly when (and in which thread) the processing for that codec takes place.

DMstatus dmXcodeWork( DMopenid openid );

openid refers to a previously-opened digital media transcoder. This function performs one unit of processing for the specified codec. The processing is done in the thread of the calling process, and the call does not return until the processing is complete. For most codecs a "unit of work" is the processing of a single buffer from the source queue and the writing of a single resulting buffer on the destination queue.

Note: Note - the default behavior for all codecs is for processing to happen automatically as a side effect of enqueueing messages to the device. This function only applies to software codecs and only applies if they are opened with the DM_XCODE_MODE_SYNCHRONOUS open option.


STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The software transcoder performed one unit of work successfully.

DM_STATUS_INVALID_ID

The specified openid is invalid.

DM_STATUS_NO_OPERATION

There was no work to be done.

RETURN EVENTS

There are no return events associated with this function.

Get Message Count

During the processing of messages it is sometimes necessary to inquire as to the “fullness” of the message queues. These functions provide that capability:

DMstatus dmGetSendMessageCount ( DMopenid openid, DMint32* messageCount);
DMstatus dmGetReceiveMessageCount ( DMopenid openid, DMint32* messageCount );

openid is a previously-opened digital media object returned by dmOpen. MessageCount is the resulting returned count.

These functions return a count of the number of messages in the send or receive queues of a device. The send queue contains messages queued by the application for processing by the device while the receive queue holds messages which have been processed and are waiting to be read by the application. A message is considered to reside in the send queue from the moment it is enqueued by the application until the moment the device begins processing it. A message resides in the receive queue from the moment the device enqueues it, until the moment the application dequeues the corresponding reply message (all messages in the receive queue are counted, regardless of whether or not they were successfully processed). The message counts are intended to aid load-balancing in sophisticated applications. They are not a reliable method for predicting UST/MSC pairs.

Some devices can begin processing one or more following messages before the first has been completed. Thus, the sum of the send and receive queue counts may be less than the difference between the number of messages which have enqueued and dequeued by the application. Note also that the time lag between a message being removed from the send queue, and the time at which it affects data passing though a physical jack, is implementation dependent. The message counts are not a reliable method for timing or synchronizing media streams.

STATUS RETURN

This function returns one of the following: DM_STATUS_NO_ERROR

The message count was obtained successfully.

DM_STATUS_INVALID_ID

The specified open device id is invalid.

Receive Messsage

In order for applications to obtain the results of previous digital media requests, the dmReceiveMessage function is used.

DMstatus dmReceiveMessage( DMopenid openid, DMint32* messageType, DMpv *reply );

openid is a previously-opened digital media object. messageType is an integer to be filled in by the device, indicating the type of message received. reply is a pointer to the head of the reply message.

This function reads the oldest message from the receive queue. The receive queue holds reply messages sent from a digital media device back to an application.

Messages on the receive queue may be the result of processing a message sent with dmSendControls, or they may result from processing a message sent with dmSendBuffers, or they may be generated spontaneously by the device to advise the application of some exceptional event.

Each message sent with an dmSendBuffers or dmSendControls generates a single reply message with messageType indicating whether or not the message was processed successfully and a pointer to a list of parameters holding the reply.

The contents of the reply array are guaranteed to remain valid until the next call to dmReceiveMessage. It is acceptable for an application to modify the reply and then send it to the same or to another device by calling dmSendControls or dmSendBuffers.

Note that, on some devices, triggering of the receive wait handle does not guarantee that a message is waiting on the receive queue. Thus applications must accept a status return of DM_STATUS_RECEIVE_QUEUE_EMPTY from an dmReceiveMessage function.

Get Returned Parameters

In returned messages, the application often wants to query specific parameters. The dmPvFind convenience function is provided for this use;

DMpv* dmPvFind( DMpv* msg, DMint64 param );

Msg is a message for which the parameter being searched is to be found. The param argument is the parameter that is being searched.

End Transfer

For an application to invoke an orderly shutdown of a digital media stream, the dmEndTransfer function should be issued.

openid is a previously-opened digital media object.

This function ends a continuous transfer on the specified path or transcoder. This call advises the device to stop processing buffers and aborts any remaining messages on its input queue. This is a blocking call. It does not return until transfers have stopped and any messages remaining on the device input queue have been aborted and flushed to the device output queue. Calling dmEndTransfer on a device which has not begun transfers is legal (it still causes the queue to be flushed). Any messages which are flushed will be marked to indicate they were aborted. Buffer messages are marked DM_BUFFERS_ABORTED, while controls messages are marked DM_CONTROLS_ABORTED.

STATUS RETURN

DM_STATUS_NO_ERROR

The device agreed to end transfer on the path.

DM_STATUS_INVALID_ID

The specified open device handle is invalid.

Close Processing

After an application is finished with a digital media connection, it should terminate that connection. The dmClose function is provided for that use. Note that an dmClose is implied if an application terminates (for any reason) before an dmClose function is called. A previously opened digital media object can be closed using:

DMstatus dmClose(DMopenid openid);

openid is the handle of the device to be closed. When a digital media object is closed, all messages in the message queues of the device are discarded. The device handle openid becomes invalid; any subsequent attempt to use it to refer to the closed object will result in an error.

dmClose returns DM_STATUS_INVALID_ID if openid is invalid. Otherwise it returns DM_STATUS_NO_ERROR after the device has been closed and associated resources have been freed.

The pipes opened as a side-effect of opening a transcoder are also closed as a side-effect of closing a transcoder. Pipes should not be closed explicitly.

Utility Functions

There are a number of other useful functions available in the DM API. They are described here.

Get Version

DMstatus dmGetVersion( DMint32 majorVersion, DMint32 minorVersion );

Use to obtain the version number for the Digital Media Library. The major version number is the first digit in the version. For example, the 1.0 release will have a major number of 1 and a minor number of 0. Changes in major numbers indicate a potential incompatibility, while changes in minor numbers indicate small backward-compatible enhancements. Within a particular major version, all the minor version numbers will start at 0 and increase monotonically. Note that this is the version number of the DM core library, the version numbers for device-dependent modules are available in the capabilities list for each physical device.

STATUS RETURN

This function returns one of the following:

DM_STATUS_NO_ERROR

The version numbers were obtained successfully.

DM_STATUS_INVALID_ARGUMENT

At least one of the pointers passed in is invalid.

Status Name

const char *dmStatusName( DMstatus status );

Intended mainly as an aid in debugging, this call converts the integer DM status value into a C string. The converted string is exactly the same as the status enum. value. For example, the value DM_STATUS_NO_ERROR, is converted to the string “DM_STATUS_NO_ERROR”.

FUNCTION RETURN

This function returns a valid C string, or NULL if the status value is invalid.

Message Name

const char *dmMessageName( DMint32 messageType );

Intended mainly as an aid in debugging, this call converts the integer DM message type into a C string. The converted string is exactly the same as the message enum values. For example, the value DM_CONTROLS_FAILED, is converted to the string "DM_CONTROLS_FAILED".

FUNCTION RETURN

This function returns a valid C string, or NULL if the message value is invalid.

DMpv String Conversion Routines

DMstatus  dmPvValueToString(DMint64 objectId, DMpv* pv, char* buffer, DMint32* bufferSize);
DMstatus  dmPvParamToString(DMint64 objectId, DMpv* pv,char* buffer, DMint32* bufferSize);
DMstatus  dmPvToString(DMint64 objectId, DMpv* pv, 	char* buffer, DMint32* bufferSize);
DMstatus  dmPvValueFromString(DMint64 objectId, const char* buffer,DMint32* bufferSize, 
                              DMpv* pv, DMbyte* arrayData, DMint32 arraySize);
DMstatus  dmPvParamFromString(DMint64 objectId, const char* buffer, DMint32* size, DMpv* pv);
DMstatus  dmPvFromString(DMint64 objectId, const char* buffer, DMint32* bufferSize, DMpv* pv,
                         DMbyte* arrayData, DMint32 arraySize);

Parameter

objectID is the 64-bit ID number for the digital media library on which the parameter is interpreted.

pv is a pointer to the DMpv for use in the conversion.

buffer is a pointer to a buffer to hold the string.

bufferSize initially contains the size of the buffer (in bytes). Upon completion, this is overwritten with the actual number of bytes processed.

arrayData is a pointer to a buffer to hold any array data resulting from the conversion.

arraySize initially contains the size of the array buffer (in bytes).

Description

These routines convert between DMpv param/value pairs and strings. They are of benefit to applications writing lists of parameters to/from files, but are most commonly used as an aid to debugging.

These routines make use of the parameter capability data (see dmPvGetCapabilities) to generate and interpret human-readable ASCII strings.

dmPvParamToString converts pv->param into a string. The resulting value for bufferSize is the length of the string (excluding the terminating '\0').

dmPvValueToString converts pv->value into a string. The resulting value for bufferSize is the length of the string (excluding the terminating '\0').

dmPvToString converts the DMpv into a string. It writes the parameter name and value separated by '='. The resulting value for bufferSize is the length of the string (excluding the terminating '\0').

dmPvParamFromString interprets a string as a parameter name and writes the result in pv->param. It expects the string was created by dmPvParamToString.

dmPvValueFromString interprets a string as the value of a DMpv and writes the result in pv->value. It expects the string was created by dmPvValueToString. For scalar parameters, the result is returned in the value field of the DMpv structure and the array arguments are not used. For array parameters, additional space is required for the result. In this case, the contents of the array are returned inside the arrayData buffer and arraySize is set to indicate the number of bytes written.

dmPvFromString interprets a string as a DMpv. It expects the string was created by dmPvToString.

Note that the interpretation of a param/value pair depends on the parameter, its value, and the device on which it will be used. Thus, all these functions require both a param/value pair and a 64-bit device identifier. That identifier may be a static id (obtained from a call to dmGetCapabilities), it may be the open id of a jack, path or transcoder (obtained from a call to dmOpen), or it may be the id of an open pipe (obtained by calling dmXcodeGetOpenPipe).

Status Return

These functions return one of the following status codes:

DM_STATUS_NO_ERROR

The conversion was performed successfully.

DM_STATUS_INVALID_ID

The specified id is invalid.

DM_STATUS_INVALID_ARGUMENT

The arguments could not be interpreted correctly. Perhaps the bufferSize or arraySize is too small to hold the result of the operation.

DM_STATUS_INVALID_PARAMETER

The parameter name is invalid. When converting to a string, the parameter name was not recognized on this device. When converting from a string, the string could not be interpreted as a valid parameter for this device.

DM_STATUS_INVALID_VALUE

The parameter value is invalid. When converting to a string, the parameter value was not recognized on this device. When converting from a string, the string could not be interpreted as a valid parameter value for this device.

Examples

This example prints the interpretation of a video timing parameter by a previously-opened video path. Note that the calls could fail if that path did not accept the particular timing value we have chosen here. Note also that, since the interpretation is coming from the device, this will work for device-specific parameters.

char buffer[200]; DMpv control;

control.param = DM_VIDEO_TIMING_INT32; control.value = DM_TIMING_1125_1920x1080_5994i;

dmPvParamToString(someOpenPath, &control;, buffer, sizeof(buffer)); 
printf("control.param is %s\n", buffer); 
dmPvValueToString(someOpenPath, &control;, buffer, sizeof(buffer)); 
printf("control.value is %s\n", buffer); 
dmPvToString(someOpenPath, &control;, buffer, sizeof(buffer)); 
printf("control is %s\n", buffer); 

The output created by this example would be:

control.param is DM_VIDEO_TIMING_INT32 control.value is DM_TIMING_1125_1920x1080_5994i control is DM_VIDEO_TIMING_INT32 = DM_TIMING_1125_1920x1080_5994i