Chapter 3. Capabilities

This chapter describes the dmSDK capabilities tree, the repository of information on all installed dmSDK devices. The capabilities tree tells you everything from the hardware location of a physical device, to the range of legal values for supported parameters.

The Capabilities Tree

The capabilities tree forms a hierarchy that describes the installed dmSDK devices in the following order from top to bottom:

  1. Physical system

  2. Physical devices

  3. Logical devices

  4. Supported parameters on the logical devices

See “Terms” in Chapter 1 for definitions of the elements of the capabilities tree hierarchy.

Figure 3-1. The Capabilities Tree

The Capabilities Tree

Utility Functions for Capabilities

To access the capability hierarchy, you may either search the capability tree directly, or make use of convenient utility functions to perform the search for you. This section discusses the baseline functionality provided in the core dmSDK library, but you may also wish to examine the utility library and example code for pre-written alternatives.

Manual Access to Capabilities

Direct access to the dmSDK capabilities tree is via three functions:

Function Call 

Description

dmGetCapabilities 

calls the capabilities for a dmSDK object

dmPvGetCapabilities 

calls the capabilities for a parameter on a given device

dmFreeCapabilities 

releases a set of capabilities when you have finished using them

Accessing Capabilities

The following code examples show you how to query for the capabilities of your entire capability tree. See “Terms” in Chapter 1 for a definition of terms used here.


Note: All objects in the dmSDK are referred to via 64-bit identifying numbers. For example, the 64-bit id number for the system on which your application is running is DM_SYSTEM_LOCALHOST.


  1. You can get the capabilities of the local system as follows. This will give you a DMpv list that includes an array of identifiers for all the physical devices installed on this system:

    Example 3-1. Get System Capabilities

    DMpv* systemCap;
    dmGetCapabilities( DM_SYSTEM_LOCALHOST, &systemCap);


  2. Use the following to list the number of physical devices on your system:

    Example 3-2. Get Physical Devices

    DMpv* deviceIds = dmPvFind( systemCap, DM_SYSTEM_DEVICE_IDS);
    printf("There are %d physical devices\n", deviceIds->length );
    if( deviceIds->length > 0 )
      printf("The first device has id %llx\n", deviceIds->value.pInt64[0]);
    dmFreeCapabilities( systemCap );


  3. The following is example code to examine a physical device for its supported I/O paths and transcoders (that is, its logical devices):

    Example 3-3. Get Logical Devices

    DMpv* deviceCap, *pathIds, *xcodeIds;
    dmGetCapabilities( someDeviceId, &deviceCap);
    pathIds = dmPvFind( deviceCap, DM_DEVICE_PATH_IDS);
    xcodeIds = dmPvFind( deviceCap, DM_DEVICE_XCODE_IDS);
    printf("Device supports %d i/o paths and %d transcoders\n", 
    pathIds->length, xcodeIds->length);
    if ( pathIds->length > 0 )
      printf("The first i/o path has id %llx\n", pathIds->value.pInt64[0]);
    dmFreeCapabilities( deviceCap );


  4. Descending still further down the capability tree, you can obtain the capabilities of any particular logical device by again calling dmGetCapabilities. For example, here you find how many parameters are accepted by a path:

    Example 3-4. Get Parameters Accepted by a Path

    DMpv* pathCap, *paramIds;
    dmGetCapabilities( somePathId, &pathCap);
    paramIds = dmPvFind( pathCap, DM_PARAM_IDS);
    printf("Path supports %d parameters\n", paramIds->length);
    if (paramIds->length > 0)
      printf("The first parameter has id %llx\n",paramIds->value.pInt64[0]);
    dmFreeCapabilities( pathCap );


Query Individual Parameters of Logical Devices

At this point, you have descended from the system to the logical device. Still there is one more level: the parameter. Querying the capabilities of a parameter is subtly different because the interpretation of parameters in the dmSDK is device-dependent (for example, the legal values for DM_IMAGE_WIDTH_INT32 may be 1920 on one device and 720 on another). Thus, you must pass both a logical device ID and a parameter ID as follows:

Example 3-5. Get Capabilities of a Parameter

DMpv* paramCap, *paramName;
dmGetCapabilities( someLogicalDeviceId, someParamId, &paramCap );
paramName = dmPvFind( paramCap, DM_NAME_BYTE_ARRAY );
if( paramName != NULL )
    printf("Param has name %s\n", (char *) ( paramName->value.pByte ));
dmFreeCapabilities( paramCap );



Note: Since the name of the parameter is being queried on a particular device, the above code will work for all parameters. This includes new device-dependent parameters.

Also, see the dmPvToString reference page for a simpler way to find a parameter name.


Query Parameters Which Describe Parameters

In addition to obtaining the capabilities of device parameters, you may also obtain the capabilities of the parameters used to describe capabilities themselves. Since the capabilities parameters are not device-dependent, deviceID may be left empty in this case. For example, here we find a text name for the capability parameter DM_PARENT_ID:

Example 3-6. Get Capabilities of Parameters that Describe Capabilities

DMpv* paramCap, *paramName;
dmGetCapabilities( 0, DM_PARENT_ID, &paramCap);
paramName = dmPvFind( paramCap, DM_NAME_BYTE_ARRAY);
if( paramName != NULL )
    printf("Param has name %s\n", (char *) ( paramName->value.pByte ));
dmFreeCapabilities( paramCap );


Again, you can get the same result by using dmPvToString, which itself calls dmPvGetCapabilities.

Identification Numbers

There are three types of ID numbers in the dmSDK:

ID Number Type 

Definition

constant 

These have defined names and may be hard-coded. They are system-independent. Examples of constant IDs are DM_SYSTEM_LOCALHOST, and DM_IMAGE_WIDTH_INT32.

static 

Static IDs are allocated by the dmSDK system as new hardware is added. They are machine-dependent and may change after a reboot, or as the system is reconfigured by adding or removing devices. The static ID of a device may change if it is removed from the system and then reconnected.


Note: Static IDs should never be written to a file or passed between machines.


Examples of static IDs are the physical and logical device IDs returned in calls to dmGetCapabilities. If you need to share such information between machines, you should use the text names (system-independent) that correspond to the static IDs.

open 

These IDs are allocated when logical devices are opened. They are machine-dependent, and have a limited lifetime -- from when dmOpen is called until dmClose is called.


Note: Open IDs should never be written to a file, or passed between machines.



Note: You can call dmGetCapabilities (or dmPvGetCapabilities) for any type of ID, but the list that is returned will always be static.


System Capabilities

The following sections describe the capabilities of each type of DM object. The capabilities are not necessarily in the order shown. In these tables, 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 name of ID is DM_ID_INT64.

Currently, the only defined physical system ID is DM_SYSTEM_LOCALHOST. When a system ID is queried, the resulting capabilities list contains the following parameters:

Table 3-1. System Capabilities

Parameter

Type

Description

ID

INT64

Resource ID for this system

NAME

BYTE_ARRAY

NULL-terminated ASCII string containing the hostname for this system.

SYSTEM_DEVICE_IDS

INT64_ARRAY

Array of physical device IDs (these need not be sorted or sequential). For more details on a particular device ID call dmGetCapabilities. This array could be of length zero.



Table 3-2. Physical Device Capabilities

Parameter

Type

Description

ID

INT64

Resource ID for this physical device.

NAME

BYTE_ARRAY

NULL-terminated ASCII description of this physical device (e.g. "HD Video I/O" or "AVC/1394").

PARENT_ID

INT64

Resource ID for the system to which this physical device is attached.

DEVICE_VERSION

INT_32

Version number for this particular physical device.

DEVICE_INDEX

BYTE_ARRAY

Index string for this physical device. This is used to distinguish multiple identical physical devices - indexes are generated with a consistent algorithm - identical machine configurations will have identical indexes - e.g. plugging a particular card into the first 64-bit, 66MHz PCI slot in any system will give the same index number. Uniquely identifying a device in a system-independent way requires using both the name and index.

DEVICE_LOCATION

BYTE_ARRAY

Physical hardware location of this physical device (on most platforms this is the hardware graph entry). Makes it possible to distinguish between two devices on the same I/O bus, and two devices each with its own I/O bus.

DEVICE_JACK_IDS

INT64_ARRAY

Array of jack IDs. For more details on a particular jack ID call dmGetCapabilities. This array could be of length zero.

DEVICE_PATH_IDS

INT64_ARRAY

Array of path IDs. For more details on a particular path ID call dmGetCapabilities. This array could be of length zero.

DEVICE_XCODE_IDS

INT64_ARRAY

Array of transcoder device IDs (these need not be sorted or sequential). For more details on a particular transcoder ID call dmGetCapabilities. This array could be of length zero.


Jack Logical Device Capabilities

The capabilities for a jack logical device contain the following parameters:

Table 3-3. Jack Logical Device Capabilities

Parameter

Type

Description

ID

INT64

Resource ID for this jack.

NAME

BYTE_ARRAY

NULL-terminated ASCII description of this jack (e.g. "Purple S-video").

PARENT_ID

INT64

Resource ID for the physical device to which this jack is attached.

JACK_TYPE

INT32

Type of logical jack: DM_JACK_TYPE_AUDIO DM_JACK_TYPE_VIDEO DM_JACK_TYPE_COMPOSITE DM_JACK_TYPE_SVIDEO DM_JACK_TYPE_SDI DM_JACK_TYPE_DUALLINK DM_JACK_TYPE_GENLOCK DM_JACK_TYPE_GPI DM_JACK_TYPE_SERIAL DM_JACK_TYPE_ANALOG_AUDIO DM_JACK_TYPE_AES DM_JACK_TYPE_GFX DM_JACK_TYPE_AUX

DM_JACK_TYPE_ADAT

Where:

AUDIO is a generic audio jack, VIDEO is a generic video jack, COMPOSITE is a composite video jack, SVIDEO is a SVideo jack, SDI is a Serial Digital Interface jack, DUALLINK is a SDI dual link jack, GENLOCK is a genlock jack, GPI is a General Purpose Interface jack, SERIAL is a generic serial control jack, ANALOG_AUDIO is an analog audio jack, AES is a digital AES standard jack, GFX is a digital graphics jack, AUX is a generic auxiliary jack, and ADAT is a digital ADAT standard jack.

JACK_DIRECTION

INT32

Direction of data flow through this jack. May be: DM_JACK_DIRECTION_IN DM_JACK_DIRECTION_OUT

Where:

IN is an input jack with data for memory and OUT is an output jack with data from memory.

JACK_COMPONENT

_SIZE

INT32

Maximum number of bits of resolution per component for the signal through this jack. Stored as an integer, so 8 means 8 bits of resolution.

JACK_PATH_IDS

INT64_ARRAY

Array of path IDs that may use this jack. (These need not be sorted or sequential.) For more details on a particular path ID, call dmGetCapabilities. This array could be of length zero.

PARAM_IDS

INT64_ARRAY

List of resource IDs for parameters which may be set and/or queried on this jack.

OPEN_OPTION_IDS

INT64_ARRAY

List of resource IDs for open option parameters which may be used when this jack is opened

JACK_FEATURES

BYTE_ARRAY

Double NULL-terminated list of ASCII features strings. Each string represents a specific feature supported by this jack. Entries are separated by NULL characters (there are 2 NULLs after the last string).



Path Logical Device Capabilities

The capabilities list for a path logical device contains the following parameters:

Table 3-4. Path Logical Device Capabilities

Parameter

Type

Resource ID for this path.

ID

INT64

Resource ID for this path.

NAME

BYTE_ARRAY

NULL-terminated ASCII description of this path (e.g., "Memory to S-Video Out").

PARENT_ID

INT64

Resource ID for the physical device on which this path resides.

PARAM_IDS

INT64_ARRAY

List of resource IDs for parameters which may be set and/or queried on this path.

OPEN_OPTION_IDS

INT64_ARRAY

List of resource IDs for open option parameters which may be used when this path is opened.

PRESET

MSG_ARRAY

Each entry in the array is a message (a pointer to the head of a DMpv list, where the last entry in the list is DM_END). Each message provides a single valid combination of all setable parameters on this path. In particular, it should be possible to call dmSetControls using any of the entries in this array as the control's message. Each path is obligated to provide at least one preset.

PATH_TYPE

INT32

Type of this path: DM_PATH_TYPE_MEM_TO_DEV DM_PATH_TYPE_DEV_TO_MEM

DM_PATH_TYPE_DEV_TO_DEV

Where: MEM_TO_DEV is a path from memory to a device, DEV_TO_MEM is a path from device to memory and DEV_TO_DEV is a path from device to another device.

PATH_COMPONENT

_ALIGNMENT

INT32

The location in memory of the first byte of a component (either an audio sample or a video line), must meet this alignment. Stored as an integer in units of bytes.

PATH_BUFFER

_ALIGNMENT

INT32

The location in memory of the first byte of an audio or video buffer must meet this alignment. Stored as an integer in units of bytes

PATH_SRC_JACK_ID

INT64

Resource ID for the jack which is the source of data for this path (unused if path is of type DM_PATH_TYPE_MEM_TO_DEV). For details on the jack ID call dmGetCapabilities.

PATH_DST_JACK_ID

INT64

Resource ID for the jack which is the destination for data from this path (unused if path is of type DM_PATH_TYPE_DEV_TO_MEM). For details on the jack ID call dmGetCapabilities.

PATH_FEATURES

BYTE_ARRAY

Double NULL-terminated list of ASCII features strings. Each string represents a specific feature supported by this path. Entries are separated by NULL characters (there are 2 NULLs after the last string).



Transcoder Logical Device Capabilities

The capabilities list for a transcoder logical device contains the following parameters:

Table 3-5. Transcoder Logical Device Capabilities

Parameter

Type

Description

ID

INT64

Resource ID for this transcoder.

NAME

BYTE_ARRAY

NULL-terminated ASCII description of this transcoder (e.g. "Software DV and DV25").

PARENT_ID

INT64

Resource ID for the physical device on which the transcoder resides.

PARAM_IDS

INT64_ARRAY

List of resource IDs for parameters which may be set and/or queried on this transcoder (May be of length 0).

OPEN_OPTION_IDS

INT64_ARRAY

List of resource IDs for open option parameters which may be used when this xcode is opened

PRESET

MSG_ARRAY

Each entry in the array is a message (a pointer to the head of a DMpv list, where the last entry in the list is DM_END). Each message provides a single valid combination of all setable parameters on a transcoder. In particular, it should be possible to call dmSetControls using any of the entries in this array as the controls message. Each transcoder is required to provide at least one preset for each transcoder.

XCODE_ENGINE_TYPE

INT32

Type of the engine in this transcoder. At this time the only defined xcode type is: DM_XCODE_ENGINE_TYPE_NULL

XCODE

_IMPLEMENTATION

_TYPE

INT32

How this transcoder is implemented: DM_XCODE_IMPLEMENTATION_TYPE_SW

DM_XCODE_IMPLEMENTATION_TYPE_HW

The implementation of the transcoder could be in either software (SW) or hardware (HW).

XCODE

_COMPONENT

_ALIGNMENT

INT32

The location in memory of the first byte of a component (either an audio sample or a video pixel), must meet this alignment. Stored as an integer in units of bytes.

XCODE

_BUFFER

_ALIGNMENT

INT32

The location in memory of the first byte of an audio or video buffer must meet this alignment. Stored as an integer in units of bytes

XCODE_FEATURES

BYTE_ARRAY

Double NULL-terminated list of ASCII features strings. Each string represents a specific feature supported by this xcode. Entries are separated by NULL characters (there are 2 NULLs after the last string)

XCODE_SRC_PIPE_IDS

INT64_ARRAY

List of pipe IDs from which the transcode engine may obtain buffers to be processes.

XCODE_DEST_PIPE_IDS

INT64_ARRAY

List of pipe IDs from which the transcode engine may obtain buffers to be filled with the result of its processing.



Pipe Logical Device Capabilities

The capabilities list for a pipe logical device contains the following parameters:

Table 3-6. Pipe Logical Device Capabilities

Parameter

Type

Description

ID

INT64

Resource ID for this path.

NAME

BYTE_ARRAY

NULL-terminated ASCII description of this pipe ("DV Codec Input Pipe").

PARENT_ID

INT64

Resource ID for the transcoder on which this pipe resides.

PARAM_IDS

INT64_ARRAY

List of resource IDs for parameters which may be set and/or queried on this transcoder (May be of length 0).

PIPE_TYPE

INT32

Type of this pipe: DM_PIPE_TYPE_MEM_TO_ENGINE

DM_PIPE_TYPE_ENGINE_TO_MEM

MEM_TO_ENGINE is the trancoder input pipe with data flow from memory to engine. ENGINE_TO_MEM is the transcoder output pipe with data flow from engine to memory.



Finding a Parameter in a Capabilities List

A parameter within a message or capabilities list may be found using

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

msg points to the first parameter in an DM_END terminated array of parameters and param is the 64-bit unique identifier of the parameter to be found. dmPvFind returns the address of the parameter if successful; otherwise it returns NULL.

Obtaining Parameter Capabilities

All objects in DM are referred to via 64-bit identifying numbers. For example, the 64-bit ID number for the system running the application is DM_SYSTEM_LOCALHOST. Details on the interpretation of a particular device dependent parameter are obtained using:

DMstatus dmPvGetCapabilities(DMint64 objectId, DMint64 parameterId, DMpv** capabilities);

objectId is the 64-bit unique identifier for the object whose parameter is being queried. An example is the openId returned from a call to dmOpen. The status DM_STATUS_INVALID_ID is returned if the specified object ID was invalid. parameterId is the 64-bit unique identifier for the parameter whose capabilities are being queried. The status DM_STATUS_INVALID_ARGUMENT is returned if the capabilities pointer is invalid. Capabilities is a pointer to the head of the resulting capabilities list. This list should be treated as read-only by the application. If the call was successful, then the status dm_STATUS_NO_ERROR is returned.

objectid may be either a static ID (obtained from a previous call to dmGetCapabilities) or an open ID (obtained by calling dmOpen.) Querying the capabilities of an opened object is identical to querying the capabilities of the corresponding static object.

It is also possible to get the capabilities of the capabilities parameters themselves. Those parameters are not tied to any particular object and so the objectId should be 0.

The list returned in capabilities contains the following parameters, though not necessarily in this order. 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 name of ID is DM_ID_INT64

Table 3-7. Parameters returned by dmPvGetCapabilities

Parameter

Type

Description

ID

INT64

Resource ID for this parameter.

NAME

BYTE_ARRAY

NULL-terminated ASCII name of this parameter. This is identical to the enumerated value. For example, if the value is DM_XXX, then the name is "DM_XXX".

PARENT_ID

INT64

Resource ID for the logical device (video path or transcoder pipe) on which this parameter is used.

PARAM_TYPE

INT32

Type of this parameter:

DM_TYPE_INT32

DM_TYPE_INT32_POINTER

DM_TYPE_INT32_ARRAY

DM_TYPE_INT64

DM_TYPE_INT64_POINTER

DM_TYPE_INT64_ARRAY

DM_TYPE_REAL32

DM_TYPE_REAL32_POINTER

DM_TYPE_REAL32_ARRAY

DM_TYPE_REAL64

DM_TYPE_REAL64_POINTER

DM_TYPE_REAL64_ARRAY

DM_TYPE_BYTE_POINTER

DM_TYPE_BYTE_ARRAY

PARAM_ACCESS

INT32

Access controls for this parameter. Bitwise "or" of the following flags:

DM_ACCESS_READ

DM_ACCESS_WRITE

DM_ACCESS_OPEN_OPTION

DM_ACCESS_IMMEDIATE(use in set/get)

DM_ACCESS_QUEUED (usein send/query)

DM_ACCESS_SEND_BUFFER (only in dmSendBuffers)

DM_ACCESS_DURING_TRANSFER

DM_ACCESS_PASS_THROUGH (ignored by device)

PARAM_DEFAULT

same type as param

Default value for this parameter of type DM_PARAM_TYPE. (This parameter may be of length 0 if there is no default).

PARAM_MINS

array of same type as param

Array of minimum values for this parameter (may be missing if there are no specified minimum values). Each set of min/max values defines one allowable range of values. If min equals max then the allowable range is a single value. If the array is of length one, then there is only one legal range of values. (will be of length 0 if there are no specified minimum values).

PARAM_MAXS

array of same type as param

Array of maximum values for this parameter (may be of length 0 if there are no specified maximum values). There is one entry in this array for each entry in the mins array.

PARAM_INCREMENT

same type as param

Legal param values go from min to max in steps of increment. (will be of length 0 if there is no increment).

PARAM_ENUM_VALUES

same type as param

Array of enumerated values for this parameter (will be of length 0 if there are no enumeration values).

PARAM_ENUM_NAMES

BYTE_ARRAY

Array of enumeration names for this parameter (must have one entry for each element in the values array). The array is a double NULL-terminated list of ASCII strings. Each string represents a specific enumeration name corresponding to the enumerated value in the same position in the PARAM_ENUM_VALUES array. Entries are separated by NULL characters (there are 2 NULLs after the last string).



Freeing Capabilities Lists

A capabilities list capabilities obtained from either dmGetCapabilities or dmPvGetCapabilities is returned to the system using DMstatus dmFreeCapabilities (DMpv *capabilities);.

The status DM_STATUS_INVALID_ARGUMENT is returned if the capabilities pointer is invalid. The DM_STATUS_NO_ERROR is returned if the call was successful.