Shared XDM Definitions

Detailed Description

This is the XDM interface.


Data Structures

struct  XDM_BufDesc
 Buffer descriptor for multiple buffers. More...
struct  XDM_SingleBufDesc
 Single buffer descriptor. More...
struct  XDM1_SingleBufDesc
 Single buffer descriptor. More...
struct  XDM1_BufDesc
 Buffer descriptor. More...
struct  XDM_AlgBufInfo
 Buffer information descriptor for input and output buffers. More...
struct  XDM_Date
 Date and time. More...
struct  XDM_Point
 2-dimensional point More...
struct  XDM_Rect
 Rectangle. More...
struct  XDM_ContextInfo
 Buffer information descriptor for input and output buffers. More...
struct  XDM_Context
 Context used by split codecs. More...

Defines

#define XDM_EOK   IALG_EOK
#define XDM_EFAIL   IALG_EFAIL
#define XDM_EUNSUPPORTED   -3
#define XDM_ERUNTIME   -2
 General runtime failure.
#define XDM_MAX_IO_BUFFERS   16
#define XDM_ISACCESSMODE_READ(x)   (((x) >> XDM_ACCESSMODE_READ) & 0x1)
 Check an access mask for CPU read access.
#define XDM_ISACCESSMODE_WRITE(x)   (((x) >> XDM_ACCESSMODE_WRITE) & 0x1)
 Check an access mask for CPU write access.
#define XDM_CLEARACCESSMODE_READ(x)   ((x) &= (~(0x1 << XDM_ACCESSMODE_READ)))
 Clear the "CPU read access" bit in an access mask.
#define XDM_CLEARACCESSMODE_WRITE(x)   ((x) &= (~(0x1 << XDM_ACCESSMODE_WRITE)))
 Clear the "CPU write access" bit in an access mask.
#define XDM_SETACCESSMODE_READ(x)   ((x) |= (0x1 << XDM_ACCESSMODE_READ))
 Set the bit to indicate CPU read access in an access mask.
#define XDM_SETACCESSMODE_WRITE(x)   ((x) |= (0x1 << XDM_ACCESSMODE_WRITE))
 Set the bit to indicate CPU write access in an access mask.
#define XDM_CUSTOMENUMBASE   0x100
 Base of algorithm-specific enum values.
#define XDM_CUSTOMCMDBASE   0x100
 Base of algorithm-specific commands.
#define XDM_ISFATALERROR(x)   (((x) >> XDM_FATALERROR) & 0x1)
#define XDM_ISUNSUPPORTEDPARAM(x)   (((x) >> XDM_UNSUPPORTEDPARAM) & 0x1)
#define XDM_ISUNSUPPORTEDINPUT(x)   (((x) >> XDM_UNSUPPORTEDINPUT) & 0x1)
#define XDM_ISCORRUPTEDHEADER(x)   (((x) >> XDM_CORRUPTEDHEADER) & 0x1)
#define XDM_ISCORRUPTEDDATA(x)   (((x) >> XDM_CORRUPTEDDATA) & 0x1)
#define XDM_ISINSUFFICIENTDATA(x)   (((x) >> XDM_INSUFFICIENTDATA) & 0x1)
#define XDM_ISAPPLIEDCONCEALMENT(x)   (((x) >> XDM_APPLIEDCONCEALMENT) & 0x1)
#define XDM_SETFATALERROR(x)   ((x) |= (0x1 << XDM_FATALERROR))
#define XDM_SETUNSUPPORTEDPARAM(x)   ((x) |= (0x1 << XDM_UNSUPPORTEDPARAM))
#define XDM_SETUNSUPPORTEDINPUT(x)   ((x) |= (0x1 << XDM_UNSUPPORTEDINPUT))
#define XDM_SETCORRUPTEDHEADER(x)   ((x) |= (0x1 << XDM_CORRUPTEDHEADER))
#define XDM_SETCORRUPTEDDATA(x)   ((x) |= (0x1 << XDM_CORRUPTEDDATA))
#define XDM_SETINSUFFICIENTDATA(x)   ((x) |= (0x1 << XDM_INSUFFICIENTDATA))
#define XDM_SETAPPLIEDCONCEALMENT(x)   ((x) |= (0x1 << XDM_APPLIEDCONCEALMENT))
#define XDM_MAX_CONTEXT_BUFFERS   32
 Maximum number of context buffers.

Enumerations

enum  XDM_AccessMode {
  XDM_ACCESSMODE_READ = 0,
  XDM_ACCESSMODE_WRITE = 1
}
 Access modes used to declare how the algorithm accessed buffers. More...
enum  XDM_CmdId {
  XDM_GETSTATUS = 0,
  XDM_SETPARAMS = 1,
  XDM_RESET = 2,
  XDM_SETDEFAULT = 3,
  XDM_FLUSH = 4,
  XDM_GETBUFINFO = 5,
  XDM_GETVERSION = 6,
  XDM_GETCONTEXTINFO = 7
}
 Standard control commands that must be implemented by XDM compliant multimedia algorithms. More...
enum  XDM_ErrorBit {
  XDM_PARAMSCHANGE = 8,
  XDM_APPLIEDCONCEALMENT = 9,
  XDM_INSUFFICIENTDATA = 10,
  XDM_CORRUPTEDDATA = 11,
  XDM_CORRUPTEDHEADER = 12,
  XDM_UNSUPPORTEDINPUT = 13,
  XDM_UNSUPPORTEDPARAM = 14,
  XDM_FATALERROR = 15
}
 Extended error information. More...
enum  XDM_DataFormat {
  XDM_BYTE = 1,
  XDM_LE_16 = 2,
  XDM_LE_32 = 3,
  XDM_LE_64 = 4,
  XDM_BE_16 = 5,
  XDM_BE_32 = 6,
  XDM_BE_64 = 7
}
 Endianness of data. More...
enum  XDM_EncodingPreset {
  XDM_DEFAULT = 0,
  XDM_HIGH_QUALITY = 1,
  XDM_HIGH_SPEED = 2,
  XDM_USER_DEFINED = 3
}
 Encoding presets. More...
enum  XDM_DecMode {
  XDM_DECODE_AU = 0,
  XDM_PARSE_HEADER = 1
}
 Decode entire access unit or only header. More...
enum  XDM_EncMode {
  XDM_ENCODE_AU = 0,
  XDM_GENERATE_HEADER = 1
}
 Encode entire access unit or only header. More...
enum  XDM_ChromaFormat {
  XDM_CHROMA_NA = -1,
  XDM_YUV_420P = 1,
  XDM_YUV_422P = 2,
  XDM_YUV_422IBE = 3,
  XDM_YUV_422ILE = 4,
  XDM_YUV_444P = 5,
  XDM_YUV_411P = 6,
  XDM_GRAY = 7,
  XDM_RGB = 8,
  XDM_YUV_420SP = 9,
  XDM_ARGB8888 = 10,
  XDM_RGB555 = 11,
  XDM_RGB565 = 12,
  XDM_YUV_444ILE = 13,
  XDM_CHROMAFORMAT_DEFAULT = XDM_YUV_422ILE
}
 Chroma formats. More...

Define Documentation

#define XDM_EOK   IALG_EOK

Success.

#define XDM_EFAIL   IALG_EFAIL

General failure.

#define XDM_EUNSUPPORTED   -3

Request is unsupported.

#define XDM_ERUNTIME   -2

General runtime failure.

Deprecated:
This is only supported on 0.9 XDM. To use it, you must define "XDM_INCLUDE_DOT9_SUPPORT". In XDM 1.00+, it is required that codecs return "EFAIL", as "ERUNTIME" is not supported.

#define XDM_MAX_IO_BUFFERS   16

Max I/O Buffers

#define XDM_ISACCESSMODE_READ ( x   )     (((x) >> XDM_ACCESSMODE_READ) & 0x1)

Check an access mask for CPU read access.

Parameters:
x access mask.
Remarks:
This is typically used by an application.
See also:
XDM1_SingleBufDesc::accessMask

XDM_ISACCESSMODE_WRITE

#define XDM_ISACCESSMODE_WRITE ( x   )     (((x) >> XDM_ACCESSMODE_WRITE) & 0x1)

Check an access mask for CPU write access.

Parameters:
x access mask.
Remarks:
This is typically used by an application.
See also:
XDM1_SingleBufDesc::accessMask

XDM_ISACCESSMODE_READ

#define XDM_CLEARACCESSMODE_READ ( x   )     ((x) &= (~(0x1 << XDM_ACCESSMODE_READ)))

Clear the "CPU read access" bit in an access mask.

Parameters:
x access mask.
Remarks:
This is typically used by an algorithm.
See also:
XDM_SETACCESSMODE_READ

XDM1_SingleBufDesc::accessMask

#define XDM_CLEARACCESSMODE_WRITE ( x   )     ((x) &= (~(0x1 << XDM_ACCESSMODE_WRITE)))

Clear the "CPU write access" bit in an access mask.

Parameters:
x access mask.
Remarks:
This is typically used by an algorithm.
See also:
XDM_SETACCESSMODE_WRITE

XDM1_SingleBufDesc::accessMask

#define XDM_SETACCESSMODE_READ ( x   )     ((x) |= (0x1 << XDM_ACCESSMODE_READ))

Set the bit to indicate CPU read access in an access mask.

Parameters:
x access mask.
Remarks:
This is typically used by an algorithm.
See also:
XDM1_SingleBufDesc::accessMask

#define XDM_SETACCESSMODE_WRITE ( x   )     ((x) |= (0x1 << XDM_ACCESSMODE_WRITE))

Set the bit to indicate CPU write access in an access mask.

Parameters:
x access mask.
Remarks:
This is typically used by an algorithm.
See also:
XDM1_SingleBufDesc::accessMask

#define XDM_CUSTOMENUMBASE   0x100

Base of algorithm-specific enum values.

Remarks:
This is provided to ensure that future updates to XDM-defined enumerations don't conflict with algorithm-proprietary enumerations.

Custom enumerations should be defined like the following (USERENUM0 and USERENUM1 are simply examples): 

  #define MYMODULE_MYVENDOR_USERENUM0 (XDM_CUSTOMENUMBASE + 0)
  #define MYMODULE_MYVENDOR_USERENUM1 (XDM_CUSTOMENUMBASE + 1)

#define XDM_CUSTOMCMDBASE   0x100

Base of algorithm-specific commands.

Remarks:
This is provided to ensure that future updates to XDM_CmdId's enumeration don't conflict with algorithm-proprietary command ID's.

Custom command ID's should be defined like the following (USERCMD0 and USERCMD1 are simply examples): 

  #define MYMODULE_MYVENDOR_USERCMD0 (XDM_CUSTOMCMDBASE + 0)
  #define MYMODULE_MYVENDOR_USERCMD1 (XDM_CUSTOMCMDBASE + 1)
See also:
XDM_CmdId

#define XDM_ISFATALERROR ( x   )     (((x) >> XDM_FATALERROR) & 0x1)

Check for fatal error

#define XDM_ISUNSUPPORTEDPARAM ( x   )     (((x) >> XDM_UNSUPPORTEDPARAM) & 0x1)

Check for unsupported parameter

#define XDM_ISUNSUPPORTEDINPUT ( x   )     (((x) >> XDM_UNSUPPORTEDINPUT) & 0x1)

Check for unsupported input

#define XDM_ISCORRUPTEDHEADER ( x   )     (((x) >> XDM_CORRUPTEDHEADER) & 0x1)

Check for corrupted header

#define XDM_ISCORRUPTEDDATA ( x   )     (((x) >> XDM_CORRUPTEDDATA) & 0x1)

Check for corrupted data

#define XDM_ISINSUFFICIENTDATA ( x   )     (((x) >> XDM_INSUFFICIENTDATA) & 0x1)

Check for insufficient data

#define XDM_ISAPPLIEDCONCEALMENT ( x   )     (((x) >> XDM_APPLIEDCONCEALMENT) & 0x1)

Check for applied concealment

#define XDM_SETFATALERROR ( x   )     ((x) |= (0x1 << XDM_FATALERROR))

Set fatal error bit

#define XDM_SETUNSUPPORTEDPARAM ( x   )     ((x) |= (0x1 << XDM_UNSUPPORTEDPARAM))

Set unsupported parameter bit

#define XDM_SETUNSUPPORTEDINPUT ( x   )     ((x) |= (0x1 << XDM_UNSUPPORTEDINPUT))

Set unsupported input bit

#define XDM_SETCORRUPTEDHEADER ( x   )     ((x) |= (0x1 << XDM_CORRUPTEDHEADER))

Set corrupted header bit

#define XDM_SETCORRUPTEDDATA ( x   )     ((x) |= (0x1 << XDM_CORRUPTEDDATA))

Set corrupted data bit

#define XDM_SETINSUFFICIENTDATA ( x   )     ((x) |= (0x1 << XDM_INSUFFICIENTDATA))

Set insufficient data bit

#define XDM_SETAPPLIEDCONCEALMENT ( x   )     ((x) |= (0x1 << XDM_APPLIEDCONCEALMENT))

Set applied concealment bit

#define XDM_MAX_CONTEXT_BUFFERS   32

Maximum number of context buffers.

Enumeration Type Documentation

enum XDM_AccessMode

Access modes used to declare how the algorithm accessed buffers.

Remarks:
This indicates how the algorithm's CPU accessed the buffer, independent of DMA or other hardware accellerators. For example, if the buffer was written to with DMA (as opposed to writing to the buffer with the CPU write instructions), the algorithm should not set the XDM_ACCESSMODE_WRITE bit.

The value of the enum is the bit offset into a mask. The value of the enum is not the value to assign the mask.

This enumeration data type should not be used for storage, but rather only for its constant values.

See also:
XDM1_SingleBufDesc

XDM1_BufDesc

Enumerator:
XDM_ACCESSMODE_READ  The algorithm read from the buffer using the CPU.

See also:
XDM_SETACCESSMODE_READ

XDM_ISACCESSMODE_READ

XDM_ACCESSMODE_WRITE  The algorithm wrote to the buffer using the CPU.

See also:
XDM_SETACCESSMODE_WRITE

XDM_ISACCESSMODE_WRITE

enum XDM_CmdId

Standard control commands that must be implemented by XDM compliant multimedia algorithms.

Remarks:
If an algorithm receives a command it doesn't handle or understand, it must return EUNSUPPORTED.

XDM_GETCONTEXTINFO need only be implemented by split codecs. Standard algorithms should return EUNSUPPORTED if they receive the XDM_GETCONTEXTINFO command.

Any control ID extension in IMOD interface should start from XDM_CUSTOMCMDBASE onward. The ID range from 0 to XDM_CUSTOMCMDBASE is reserved.

This enumeration data type should not be used for storage, but rather only for its constant values.

See also:
XDM_CUSTOMCMDBASE
Enumerator:
XDM_GETSTATUS  Query algorithm to fill status structure.
XDM_SETPARAMS  Set run time dynamic parameters.
XDM_RESET  Reset the algorithm. All fields in the internal data structures are reset and all internal buffers are flushed.
XDM_SETDEFAULT  Restore the algorithm's internal state to its original, default values.

Remarks:
The application only needs to initialize the dynamicParams.size and status.size fields prior to calling control() with XDM_SETDEFAULT.

The algorithm must only write to the status.extendedError field, and potentially algorithm specific, extended fields.

XDM_SETDEFAULT differs from XDM_RESET. In addition to restoring the algorithm's internal state, XDM_RESET additionally resets any channel related state.

XDM_FLUSH  Handle end of stream conditions. This command forces the algorithm to output data without additional input. The recommended sequence is to call the control() function (with XDM_FLUSH) followed by repeated calls to the process() function until it returns an error.

Remarks:
The algorithm should return the appropriate, class-specific "EFAIL" error (e.g. ISPHDEC1_EFAIL, IVIDENC1_EFAIL, etc), when flushing is complete.
XDM_GETBUFINFO  Query algorithm instance regarding its properties of input and output buffers.

Remarks:
The application only needs to initialize the dynamicParams.size, the status.size, and set any buffer descriptor fields (e.g. status.data) to NULL prior to calling control() with XDM_GETBUFINFO.
XDM_GETVERSION  Query the algorithm's version. The result will be returned in the data field of the respective _Status structure.

Remarks:
There is no specific format defined for version returned by the algorithm.
XDM_GETCONTEXTINFO  Query a split codec part for its context needs.

Remarks:
Only split codecs are required to implement this command.

enum XDM_ErrorBit

Extended error information.

Remarks:
When an internal error occurs, the algorithm will return an error return value (e.g. EFAIL, EUNSUPPORTED)

The value of each enum is the bit which is set.

Bits 31-16 are reserved. Bits 7-0 are codec and implementation specific.

The algorithm can set multiple bits to 1 based on conditions. e.g. it will set bits XDM_FATALERROR (fatal) and XDM_UNSUPPORTEDPARAM (unsupported params) in case of unsupported run time parameters.

This enumeration data type should not be used for storage, but rather only for its constant values.

Enumerator:
XDM_PARAMSCHANGE  Bit 8 - Sequence Parameters Change.

Remarks:
This error is applicable for transcoders. It is set when some key parameter of the input sequence changes. The transcoder simply returns after setting this error field and the correct input sequence parameters are updated in outArgs.
XDM_APPLIEDCONCEALMENT  Bit 9 - Applied concealment.

Remarks:
This error is applicable for decoders. It is set when the decoder was not able to able to decode the bitstream, and the decoder has concealed the bitstream error and produced the concealed output.
XDM_INSUFFICIENTDATA  Bit 10 - Insufficient input data.

Remarks:
This error is typically applicable for decoders. This is set when the input data provided is not sufficient to produce of one frame of data. This can be also be set for encoders when the number of valid samples in the input frame is not sufficient to process a frame.
XDM_CORRUPTEDDATA  Bit 11 - Data problem/corruption.

Remarks:
This error is typically applicable for decoders. This is set when the bitstream has an error and not compliant to the standard syntax.
XDM_CORRUPTEDHEADER  Bit 12 - Header problem/corruption.

Remarks:
This error is typically applicable for decoders. This is set when the header information in the bitstream is incorrect. For example, it is set when Sequence/Picture/Slice etc. are incorrect in video decoders.
XDM_UNSUPPORTEDINPUT  Bit 13 - Unsupported feature/parameter in input.

Remarks:
This error is set when the algorithm is not able process a certain input data/bitstream format. It can also be set when a subset of features in a standard are not supported by the algorithm.

For example, if a video encoder only supports 4:2:2 format, it can set this error for any other type of input video format.

XDM_UNSUPPORTEDPARAM  Bit 14 - Unsupported input parameter or configuration.

Remarks:
This error is set when the algorithm doesn't support certain configurable parameters. For example, if the video decoder doesn't support the "display width" feature, it shall return XDM_UNSUPPORTEDPARAM when the control function is called for setting the displayWidth attribute.
XDM_FATALERROR  Bit 15 - Fatal error (stop the codec). If there is an error and this bit is not set, the error is a recoverable one.

Remarks:
This error is set when the algorithm cannot recover from the current state. It informs the system not to try the next frame and possibly delete the multimedia algorithm instance. It implies the codec shall not work when reset.

The user should delete the current instance of the codec.

enum XDM_DataFormat

Endianness of data.

Remarks:
This enumeration data type should not be used for storage, but rather only for its constant values.

This enumeration defines a base set of values. Algorithms which require proprietary enumeration values may define them - much like extended fields in base structures. These extended enums should be between XDM_CUSTOMENUMBASE and 0x7FFF.

See also:
XDM_CUSTOMENUMBASE
Enumerator:
XDM_BYTE  Big endian stream.
XDM_LE_16  16 bit little endian stream.
XDM_LE_32  32 bit little endian stream.
XDM_LE_64  64 bit little endian stream.
XDM_BE_16  16 bit big endian stream.
XDM_BE_32  32 bit big endian stream.
XDM_BE_64  64 bit big endian stream.

enum XDM_EncodingPreset

Encoding presets.

Remarks:
This enumeration data type should not be used for storage, but rather only for its constant values.

This enumeration defines a base set of values. Algorithms which require proprietary enumeration values may define them - much like extended fields in base structures. These extended enums should be between XDM_CUSTOMENUMBASE and 0x7FFF.

See also:
XDM_CUSTOMENUMBASE
Enumerator:
XDM_DEFAULT  Default setting of encoder. See codec specific documentation for its encoding behaviour.
XDM_HIGH_QUALITY  High quality encoding.
XDM_HIGH_SPEED  High speed encoding.
XDM_USER_DEFINED  User defined configuration, using advanced parameters.

enum XDM_DecMode

Decode entire access unit or only header.

Remarks:
This enumeration data type should not be used for storage, but rather only for its constant values.

This enumeration defines a base set of values. Algorithms which require proprietary enumeration values may define them - much like extended fields in base structures. These extended enums should be between XDM_CUSTOMENUMBASE and 0x7FFF.

See also:
XDM_CUSTOMENUMBASE
Enumerator:
XDM_DECODE_AU  Decode entire access unit, including all the headers.
XDM_PARSE_HEADER  Decode only header.

enum XDM_EncMode

Encode entire access unit or only header.

Remarks:
This enumeration data type should not be used for storage, but rather only for its constant values.

This enumeration defines a base set of values. Algorithms which require proprietary enumeration values may define them - much like extended fields in base structures. These extended enums should be between XDM_CUSTOMENUMBASE and 0x7FFF.

See also:
XDM_CUSTOMENUMBASE
Enumerator:
XDM_ENCODE_AU  Encode entire access unit, including the headers.
XDM_GENERATE_HEADER  Encode only header.

enum XDM_ChromaFormat

Chroma formats.

Remarks:
This enumeration data type should not be used for storage, but rather only for its constant values.

This enumeration defines a base set of values. Algorithms which require proprietary enumeration values may define them - much like extended fields in base structures. These extended enums should be between XDM_CUSTOMENUMBASE and 0x7FFF.

See also:
XDM_CUSTOMENUMBASE
Enumerator:
XDM_CHROMA_NA  Chroma format not applicable.
XDM_YUV_420P  YUV 4:2:0 planer.
XDM_YUV_422P  YUV 4:2:2 planer.
XDM_YUV_422IBE  YUV 4:2:2 interleaved (big endian).
XDM_YUV_422ILE  YUV 4:2:2 interleaved (little endian).
XDM_YUV_444P  YUV 4:4:4 planer.
XDM_YUV_411P  YUV 4:1:1 planer.
XDM_GRAY  Gray format.
XDM_RGB  RGB color format.
XDM_YUV_420SP  YUV 420 semi_planar format.(Luma 1st plane, CbCr interleaved 2nd plane)
XDM_ARGB8888  Alpha plane.
XDM_RGB555  RGB 555 color format.
XDM_RGB565  RGB 565 color format.
XDM_YUV_444ILE  YUV 4:4:4 interleaved (little endian).
XDM_CHROMAFORMAT_DEFAULT  Default setting.

Copyright 2009, Texas Instruments Incorporated