Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    Multimedia Formats

Multimedia

Exploring Palm OS®

This chapter describes multimedia structures, types, constants, and functions related to formats. It covers:

Multimedia Format Structures and Types
Multimedia Format Constants
Multimedia Format Functions and Macros

The header files MMFormatDefs.h and MMFormat.h declare the API that this chapter describes.

Multimedia Format Structures and Types ^TOP^

MMFormat Typedef ^TOP^

Purpose

Identifies a multimedia format object.

Declared In

MMFormat.h

Prototype

typedef int32_t MMFormat

MMFormatType Typedef ^TOP^

Purpose

Identifies a multimedia format type.

Declared In

MMFormat.h

Prototype

typedef int32_t MMFormatType

Comments

Format types are defined by the formatType enum.

Multimedia Format Constants ^TOP^

Format Key Constants ^TOP^

Purpose

Values used as keys to format terms. The descriptions below explain what the value is for each key. Each value is a 32-bit integer unless otherwise specified.

Declared In

MMFormatDefs.h

Constants

#define P_FORMATKEY_BYTE_ORDER "byte_order"
The byte order for raw audio. Possible values are LITTLE_ENDIAN, BIG_ENDIAN, or HOST_ENDIAN.
#define P_FORMATKEY_RAW_AUDIO_TYPE "raw_audio_type"
Base type used for raw audio. Possible values are fmtRawAudioType.
#define P_FORMATKEY_RAW_AUDIO_BITS "raw_audio_bits"
If P_FORMATKEY_RAW_AUDIO_TYPE is P_AUDIO_INT32, the value for this provides the actual number of bits used in a given 32-bit sample.
#define P_FORMATKEY_CHANNEL_USAGE "channel_usage"
Number of audio channels for a raw, ADPCM, or MPEG audio stream. Possible values are fmtAudioChannelUsage.
#define P_FORMATKEY_ENCODED_BIT_RATE "enc_bit_rate"
The audio or video bit rate for MPEG formats.
#define P_FORMATKEY_FRAME_RATE "frame_rate"
A floating-point value specifying the number of frames processed per second for an audio or video stream.
#define P_FORMATKEY_BUFFER_FRAMES "buffer_frames"
An integer specifying the number of frames per buffer for audio data.
#define P_FORMATKEY_WIDTH "width"
Width in native pixels of a video frame or graphics file.
#define P_FORMATKEY_HEIGHT "height"
Height in native pixels of a video frame or graphics file.
#define P_FORMATKEY_BYTES_PER_ROW "bytes_per_row"
An integer specifying the number of bytes per row of a raw video frame or of a graphics file.
#define P_FORMATKEY_PIXEL_FORMAT "pixel_format"
64-bit integer describing the pixel format of a raw video frame or of a graphics file.
#define P_FORMATKEY_VIDEO_ORIENTATION "video_orientation"
Video orientation for graphics still. Possible values are defined in fmtVideoOrientation.
#define P_FORMATKEY_MSADPCM_BITS_PER_SAMPLE "msadpcm_sample_bits"
Number of bits per sample for a mono-channel MS-ADPCM sound stream.
#define P_FORMATKEY_MSADPCM_COEFS "msadpcm_coefs"
Variable size 16-bit coefficient table in host-endian format.
#define P_FORMATKEY_MPEG12_AUDIO_REVISION "mpeg12_audio_rev"
The specific version of MPEG audio. Possible values are defined in fmtMPEG12AudioRevision.
#define P_FORMATKEY_MPEG12_AUDIO_LAYER "mpeg12_audio_layer"
MPEG-1 or MPEG-2 audio layer. Possible values are in fmtMPEG12AudioLayer.
#define P_FORMATKEY_MPEG12_AUDIO_CHANNEL_MODE "mpeg12_audio_channel_mode"
MPEG-1 or MPEG-2 audio channel mode. Possible values are defined in fmtMPEG12AudioChannelMode.
#define P_FORMATKEY_DVIADPCM_BITS_PER_SAMPLE "dviadpcm_sample_bits"
Number of bits per sample in a mono-channel Intel/DVI ADPCM audio file.
#define P_FORMATKEY_MPEG4AUDIO_OBJECT_PROFILE "mpeg4audio_object_profile"
Type of audio object profile used for MPEG-4 audio. Possible values are defined in fmtMPEG4AudioObjectProfile.
#define P_FORMATKEY_MPEG4AUDIO_TF_CODING "mpeg4audio_tf_coding"
MPEG-4 audio track time/frequency coding format. Possible values are defined in fmtMPEG4AudioTFCoding.
#define P_FORMATKEY_MPEG4AUDIO_TF_FRAME_LENGTH "mpeg4audio_tf_frame_length"
Frame length for MPEG-4 audio time/frequency coding format.
#define P_FORMATKEY_MPEG4AUDIO_TF_CORE_CODER_DELAY "mpeg4audio_tf_core_coder_delay"
Parameter for MPEG-4 audio (AAC) decoding.
#define P_FORMATKEY_MPEG4AUDIO_TF_LSLAYER_LENGTH "mpeg4audio_tf_lslayer_length"
Parameter for MPEG-4 audio (AAC) decoding.
#define P_FORMATKEY_MPEG4AUDIO_TF_PCE "mpeg4audio_tf_pce"
Parameter for MPEG-4 audio (AAC) decoding.
#define P_FORMATKEY_MPEG4VIDEO_VOP_TIME_INC_RESOLUTION "mpeg4video_vop_time_inc_res"
MPEG-4 video object plane temporal resolution.
#define P_FORMATKEY_YCBCR420_PLANAR_VIDEO_UV_STRIDE "ycbcr420_uv_stride"
The distance in bytes from one row to the next.
#define P_FORMATKEY_YCBCR420_PLANAR_VIDEO_Y_STRIDE "ycbcr420_y_stride"
The distance in bytes from one row to the next.

fmtAudioChannelUsage Enum ^TOP^

Purpose

Values for the key P_FORMATKEY_CHANNEL_USAGE.

Declared In

MMFormatDefs.h

Constants

P_STEREO = 0x02
Stereo.
P_MONO = 0x01
Mono.
P_DOLBY_PRO_LOGIC_STEREO = 0x12
Dolby digital pro logic stereo.
P_DOLBY_5_1_SURROUND = 0x26
Dolby digital 5.1 format stereo.
P_DTS_SURROUND = 0x36
Sony DTS surround stereo.
P_CHANNEL_COUNT_MASK = 0x0f
When you AND a channel usage constant with this mask, you get the actual number of audio channels.

fmtMPEG12AudioChannelMode Enum ^TOP^

Purpose

Values for the key P_FORMATKEY_MPEG12_AUDIO_CHANNEL_MODE.

Declared In

MMFormatDefs.h

Constants

P_MPEG12_AUDIO_STEREO = 2
Stereo (2 channels).
P_MPEG12_AUDIO_JOINT_STEREO = 0x82
Joint stereo.
P_MPEG12_AUDIO_DUAL_CHANNEL = 0x42
Dual channel.
P_MPEG12_AUDIO_MONO = 1
Mono (single channel).
P_MPEG12_AUDIO_CHANNEL_COUNT_MASK = 0x0f
Mask of all channel mode values.

fmtMPEG12AudioEmphasis Enum ^TOP^

Purpose

For internal use only.

Declared In

MMFormatDefs.h

Constants

P_MPEG12_AUDIO_EMPHASIS_NONE = 0
P_MPEG12_AUDIO_EMPHASIS_50_15ms = 1
P_MPEG12_AUDIO_EMPHASIS_CCITT_J17 = 3

fmtMPEG12AudioLayer Enum ^TOP^

Purpose

Possible audio layers implemented in MPEG-1 and MPEG-2.

Declared In

MMFormatDefs.h

Constants

P_MPEG12_AUDIO_LAYER_I
Audio layer 1.
P_MPEG12_AUDIO_LAYER_II
Audio layer 2.
P_MPEG12_AUDIO_LAYER_III
Audio layer 3 (MP3).

fmtMPEG12AudioRevision Enum ^TOP^

Purpose

Possible versions when the format is MPEG-1 or MPEG-2.

Declared In

MMFormatDefs.h

Constants

P_MPEG12_AUDIO_REV_MPEG1
MPEG-1.
P_MPEG12_AUDIO_REV_MPEG2
MPEG-2.
P_MPEG12_AUDIO_REV_MPEG2_5
MPEG-2.5.

fmtMPEG4AudioObjectProfile Enum ^TOP^

Purpose

Values for the key P_FORMATKEY_MPEG4AUDIO_OBJECT_PROFILE.

Declared In

MMFormatDefs.h

Constants

P_MPEG4AUDIO_AAC_MAIN = 1
Advanced Audio Coding (AAC) main.
P_MPEG4AUDIO_AAC_LC
Low-complexity AAC.
P_MPEG4AUDIO_AAC_SSR
Scalable sampling rate.
P_MPEG4AUDIO_AAC_LTP
AAC coder including long term prediction.
P_MPEG4AUDIO_AAC_SCALABLE = 6
AAC scalable.
P_MPEG4AUDIO_TWINVQ
TwinVQ audio profile.
P_MPEG4AUDIO_CELP
CELP speech coder.
P_MPEG4AUDIO_HVXC
HVXC speech coder.
P_MPEG4AUDIO_TTSI = 12
Text-to-speech interface.
P_MPEG4AUDIO_MAIN_SYNTHETIC
Synthesis profile.
P_MPEG4AUDIO_WAVETABLE
Wavetable synthesis.
P_MPEG4AUDIO_GENERAL_MIDI
General MIDI synthesis.
P_MPEG4AUDIO_ALGORITHMIC
Algorithmic synthesis.
P_MPEG4AUDIO_ER_AAC_LC
Error-resilient low-complexity AAC.
P_MPEG4AUDIO_ER_AAC_LTP
Error-resilient AAC coder including long term prediction.
P_MPEG4AUDIO_ER_AAC_SCALABLE
Error-resilient AAC scalable.
P_MPEG4AUDIO_ER_TWINVQ
Error-resilient TwinVQ audio profile.
P_MPEG4AUDIO_ER_BSAC
Error-resilient bit-sliced arithmetic coding.
P_MPEG4AUDIO_ER_AAC_LD
Error-resilient low-delay AAC.
P_MPEG4AUDIO_ER_CELP
Error-resilient CELP speech coder.
P_MPEG4AUDIO_ER_HVXC
Error-resilient HVXC speech coder.
P_MPEG4AUDIO_ER_HILN
Error-resilient HILN parametric coding.
P_MPEG4AUDIO_ER_PARAMETRIC
Error-resilient parametric coding.

fmtMPEG4AudioTFCoding Enum ^TOP^

Purpose

Values for P_FORMATKEY_MPEG4AUDIO_TF_CODING.

Declared In

MMFormatDefs.h

Constants

P_MPEG4AUDIO_TF_AAC_SCALABLE
AAC scalable.
P_MPEG4AUDIO_TF_BSAC
Bit-sliced arithmetic coding.
P_MPEG4AUDIO_TF_TWINVQ
Twin VQ.
P_MPEG4AUDIO_TF_AAC_NON_SCALABLE
AAC non-scalable.

fmtRawAudioType Enum ^TOP^

Purpose

Values for the key P_FORMATKEY_RAW_AUDIO_TYPE.

Declared In

MMFormatDefs.h

Constants

P_AUDIO_INT8 = 0x01
8-bit integer.
P_AUDIO_UINT8 = 0x11
8-bit unsigned integer.
P_AUDIO_INT16 = 0x02
16-bit integer.
P_AUDIO_INT32 = 0x04
32-bit integer.
P_AUDIO_FLOAT = 0x24
Floating-point value.
P_AUDIO_SIZE_MASK = 0x0f
When you AND a raw audio type constant with this mask, you get the actual audio sample size in bytes.

fmtVideoOrientation Enum ^TOP^

Purpose

Values for the key P_FORMATKEY_VIDEO_ORIENTATION.

Declared In

MMFormatDefs.h

Constants

P_VIDEO_TOP_LEFT_RIGHT = 1
Start at the top and move left to right.
P_VIDEO_BOTTOM_LEFT_RIGHT
Start at the bottom and scan left to right.

formatFamily Enum ^TOP^

Purpose

Values of the first byte in a formatType.

Declared In

MMFormatDefs.h

Constants

P_FORMAT_FAMILY_MPEG12 = 1
MPEG-1 or MPEG-2 multimedia file.
P_FORMAT_FAMILY_MPEG4 = 3
MPEG-4 multimedia file.
P_FORMAT_FAMILY_ATRAC
Adaptive Transform Acoustic Coding for MiniDisc sound file.
P_FORMAT_FAMILY_H263
H.263 multimedia format.
P_FORMAT_FAMILY_3GPP
3GPP multimedia format file.
P_FORMAT_FAMILY_AVI
Microsoft's video for Windows standard.
P_FORMAT_FAMILY_QUICKTIME
Apple QuickTime video standard.
P_FORMAT_FAMILY_ASF
Microsoft advanced streaming format multimedia.
P_FORMAT_FAMILY_WAV
WAV format sound files.
P_FORMAT_FAMILY_AIFF
Audio Interchange File Format for sampled sound.
P_FORMAT_FAMILY_JPEG
A JPEG graphic file.
P_FORMAT_FAMILY_GIF
A GIF graphic file.
P_FORMAT_FAMILY_BMP
A BMP graphic file.
P_FORMAT_FAMILY_PNG
A PNG graphic file.
P_FORMAT_FAMILY_TIFF
A TIFF graphic file.
P_FORMAT_FAMILY_RAW
Raw format for audio or video.
P_FORMAT_FAMILY_YCBCR420
YCbCr420 video format.
P_FORMAT_FAMILY_OGG
Ogg Vorbis format.
P_FORMAT_FAMILY_AMR
3GPP AMR speech format.
P_FORMAT_FAMILY_G7XX
CCITT 7xx voice compression formats.
P_FORMAT_FAMILY_H264
H264 video file.
P_FORMAT_FAMILY_CINEPAK
SuperMac Cinepak video format.
P_FORMAT_FAMILY_USER = 0xfd
User-defined format.
P_FORMAT_FAMILY_PRIVATE = 0xfe
Private format.
P_FORMAT_FAMILY_PALMOS_INTERNAL = 0xff
Internal to Palm OS®.

formatType Enum ^TOP^

Purpose

Values of format types.

Declared In

MMFormatDefs.h

Constants

P_FORMAT_UNKNOWN = 0
Unknown format.
P_FORMAT_ANY_TYPE = 0xff
Matches any format.
P_FORMAT_AUDIO_TYPE = 0x01
Any audio format.
P_FORMAT_VIDEO_TYPE = 0x02
Any video format.
P_FORMAT_MIDI_TYPE = 0x04
Matches any MIDI sound type.
P_FORMAT_STILL_TYPE = 0x08
Matches any still graphic file.
P_FORMAT_RAW_AUDIO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_RAW, P_FORMAT_AUDIO_TYPE),
Raw audio format.
P_FORMAT_RAW_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_RAW, P_FORMAT_VIDEO_TYPE)
Raw video format.
P_FORMAT_MIDI = _MMFORMATTYPE(0, P_FORMAT_FAMILY_RAW, P_FORMAT_MIDI_TYPE),
Raw MIDI sound file.
P_FORMAT_RAW_STILL = _MMFORMATTYPE(0, P_FORMAT_FAMILY_RAW, P_FORMAT_STILL_TYPE)
Raw graphics file.
P_FORMAT_MPEG12_AUDIO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_MPEG12, P_FORMAT_AUDIO_TYPE)
MPEG-1 or MPEG-2 audio track.
P_FORMAT_MPEG12_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_MPEG12, P_FORMAT_VIDEO_TYPE)
MPEG-1 or MPEG-2 video track.
P_FORMAT_MPEG4_AUDIO_TF =
_MMFORMATTYPE(0x01, P_FORMAT_FAMILY_MPEG4, P_FORMAT_AUDIO_TYPE)
MPEG-4 audio track time/frequency coder.
P_FORMAT_MPEG4_AUDIO_CELP =
_MMFORMATTYPE(0x02, P_FORMAT_FAMILY_MPEG4, P_FORMAT_AUDIO_TYPE)
MPEG-4 audio track code excited linear prediction.
P_FORMAT_MPEG4_AUDIO_PARAMETRIC =
_MMFORMATTYPE(0x03, P_FORMAT_FAMILY_MPEG4, P_FORMAT_AUDIO_TYPE)
MPEG-4 audio track with parametric coding.
P_FORMAT_MPEG4_AUDIO_TTS =
_MMFORMATTYPE(0x04, P_FORMAT_FAMILY_MPEG4, P_FORMAT_AUDIO_TYPE)
MPEG-4 audio text-to-speech track.
P_FORMAT_MPEG4_AUDIO_STRUCTURED =
_MMFORMATTYPE(0x05, P_FORMAT_FAMILY_MPEG4, P_FORMAT_AUDIO_TYPE)
MPEG-4 audio track with structured format.
P_FORMAT_MPEG4_VIDEO =
_MMFORMATTYPE(0, P_FORMAT_FAMILY_MPEG4, P_FORMAT_VIDEO_TYPE)
MPEG-4 video track.
P_FORMAT_ATRAC_AUDIO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_ATRAC, P_FORMAT_AUDIO_TYPE)
ATRAC audio track.
P_FORMAT_H263_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_H263, P_FORMAT_VIDEO_TYPE)
H.263 video track.
P_FORMAT_MSADPCM_AUDIO =
_MMFORMATTYPE(0x02, P_FORMAT_FAMILY_WAV, P_FORMAT_AUDIO_TYPE)
A WAV (MS-ADPCM) audio track.
P_FORMAT_DVI_ADPCM_AUDIO =
_MMFORMATTYPE(0x11, P_FORMAT_FAMILY_WAV, P_FORMAT_AUDIO_TYPE)
Intel/DVI ADPCM audio track.
P_FORMAT_JPEG_STILL = _MMFORMATTYPE(0, P_FORMAT_FAMILY_JPEG, P_FORMAT_STILL_TYPE)
JPEG graphics file.
P_FORMAT_BMP_STILL = _MMFORMATTYPE(0, P_FORMAT_FAMILY_BMP, P_FORMAT_STILL_TYPE)
BMP graphics file.
P_FORMAT_PNG_STILL = _MMFORMATTYPE(0, P_FORMAT_FAMILY_PNG, P_FORMAT_STILL_TYPE)
PNG graphics file.
P_FORMAT_TIFF_STILL = _MMFORMATTYPE(0, P_FORMAT_FAMILY_TIFF, P_FORMAT_STILL_TYPE)
TIFF graphics file.
P_FORMAT_YCBCR420_PLANAR_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_YCBCR420, P_FORMAT_VIDEO_TYPE)
Video track with YCbCr420 planar format.
P_FORMAT_OGG_VORBIS_AUDIO =
_MMFORMATTYPE(0x01, P_FORMAT_FAMILY_OGG, P_FORMAT_AUDIO_TYPE)
Ogg Vorbis audio format track.
P_FORMAT_AMR_TS26_071_AUDIO =
_MMFORMATTYPE(0x01, P_FORMAT_FAMILY_AMR, P_FORMAT_AUDIO_TYPE)
GSM AMR speech format audio track.
P_FORMAT_AMR_TS26_171_AUDIO =
_MMFORMATTYPE(0x02, P_FORMAT_FAMILY_AMR, P_FORMAT_AUDIO_TYPE)
AMR wideband speech format audio track.
P_FORMAT_G711_AUDIO = _MMFORMATTYPE(0x01, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE)
CCITT G711 voice compression audio track.
P_FORMAT_G722_AUDIO = _MMFORMATTYPE(0x02, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE)
CCITT G722 voice compression audio track.
P_FORMAT_G723_AUDIO = _MMFORMATTYPE(0x03, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE)
CCITT G723 voice compression audio track.
P_FORMAT_G723_1_AUDIO = _MMFORMATTYPE(0x04, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE),
CCITT G732.1 voice compression audio track.
P_FORMAT_G726_AUDIO = _MMFORMATTYPE(0x05, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE),
CCITT G726 voice compression audio track.
P_FORMAT_G728_AUDIO = _MMFORMATTYPE(0x06, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE),
CCITT G728 voice compression audio track.
P_FORMAT_G729_AUDIO = _MMFORMATTYPE(0x07, P_FORMAT_FAMILY_G7XX, P_FORMAT_AUDIO_TYPE),
CCITT G729 voice compression audio track.
P_FORMAT_H264_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_H264, P_FORMAT_VIDEO_TYPE)
H264 video track.
P_FORMAT_CINEPAK_VIDEO = _MMFORMATTYPE(0, P_FORMAT_FAMILY_CINEPAK, P_FORMAT_VIDEO_TYPE)
Cinepack video track.
P_FORMAT_STREAM_TYPE = 0x10
Matches any streaming type.
P_FORMAT_MPEG12_STREAM =
_MMFORMATTYPE(0, P_FORMAT_FAMILY_MPEG12, P_FORMAT_STREAM_TYPE)
An MPEG-1 or MPEG-2 streaming video.
P_FORMAT_MPEG4_STREAM =
_MMFORMATTYPE(0, P_FORMAT_FAMILY_MPEG4, P_FORMAT_STREAM_TYPE)
An MPEG-4 streaming video.
P_FORMAT_MQV_STREAM = _MMFORMATTYPE(0x01, P_FORMAT_FAMILY_MPEG4, P_FORMAT_STREAM_TYPE)
An MQV streaming video.
P_FORMAT_ATRAC_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_ATRAC, P_FORMAT_STREAM_TYPE)
ATRAC streaming video.
P_FORMAT_AVI_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_AVI, P_FORMAT_STREAM_TYPE)
Microsoft's video for Windows streaming video.
P_FORMAT_QUICKTIME_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_QUICKTIME, P_FORMAT_STREAM_TYPE)
QuickTime streaming video.
P_FORMAT_ASF_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_ASF, P_FORMAT_STREAM_TYPE)
Advanced streaming format video.
P_FORMAT_WAV_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_WAV, P_FORMAT_STREAM_TYPE)
MS-ADPCM streaming sound.
P_FORMAT_AIFF_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_AIFF, P_FORMAT_STREAM_TYPE)
AIFF streaming sound.
P_FORMAT_BMP_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_BMP, P_FORMAT_STREAM_TYPE)
A BMP streaming video file.
P_FORMAT_JPEG_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_JPEG, P_FORMAT_STREAM_TYPE)
A JPEG streaming video file.
P_FORMAT_PNG_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_PNG, P_FORMAT_STREAM_TYPE)
A PNG streaming video file.
P_FORMAT_TIFF_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_TIFF, P_FORMAT_STREAM_TYPE)
A TIFF streaming video file.
P_FORMAT_OGG_VORBIS_STREAM = _MMFORMATTYPE(0, P_FORMAT_FAMILY_OGG, P_FORMAT_STREAM_TYPE)
Ogg Vorbis streaming sound.

Miscellaneous Constants ^TOP^

Purpose

Other constants.

Declared In

MMFormatDefs.h, MMFormat.h

Constants

#define P_FORMAT_MAX_KEY_LENGTH 64
Maximum length of a format key.
#define P_MM_INVALID_FORMAT 0
Invalid format.

Multimedia Format Functions and Macros ^TOP^

_MMFORMATTYPE Macro ^TOP^

Purpose

Defines a value for a media format type like those in the formatType enum.

Declared In

MMFormatDefs.h

Prototype

#define _MMFORMATTYPE(
   subtype,
   family,
   type
)

Parameters

subtype
An 8-bit integer that describes a family subtype.
family
An 8-bit integer that describes a format family using one of the formatFamily constants.
type
An 8-bit integer that describes the basic media type: audio track, video track, or stream. Only 5 bits are currently used. The remaining 3 are reserved for future type expansion.

Returns

A 32-bit constant that uniquely identifies a multimedia format.

Comments

If you need to define a format type for a proprietary format, use P_FORMAT_FAMILY_PRIVATE as the family.

MMFormatCopy Function ^TOP^

Purpose

Creates a new media format object by copying an existing media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatCopy (
   MMFormat *outDest,
   MMFormat source
)

Parameters

outDest
Pointer to the newly created media format object that is identical to source.
source
A valid media format object.

Returns

errNone if the function was successful, otherwise an appropriate Multimedia Library error.

Comments

The caller is responsible for calling MMFormatDelete() on the newly created media format object when they no longer need it.

MMFormatCreate Function ^TOP^

Purpose

Creates a new media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatCreate (
   MMFormat *outFormat
)

Parameters

outFormat
Pointer to the newly created media format object.

Returns

errNone if the function was successful, otherwise an appropriate Multimedia Library error.

Comments

The caller is responsible for calling MMFormatDelete() on the newly created media format object when they no longer need it.

MMFormatDelete Function ^TOP^

Purpose

Deletes a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatDelete (
   MMFormat format
)

Parameters

format
A valid media format object.

Returns

errNone if the function was successful, otherwise an appropriate Multimedia Library error.

MMFormatEnumerateTerms Function ^TOP^

Purpose

Lists the terms in a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatEnumerateTerms (
   MMFormat format,
   int32_t *ioIterator,
   char *outKey,
   MMTypeCode *outType
)

Parameters

format
A valid media format object.
ioIterator
Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to P_MM_ENUM_BEGIN. When the set of iterated values is exhausted, this function sets this value to P_MM_ENUM_END.
outKey
Pointer to the key for the current term. This must point to a buffer of size P_FORMAT_MAX_KEY_LENGTH or larger.
outType
Pointer to the data type of the current term. Unspecified wildcard terms may have type P_MM_TYPE_WILD (in which case they contain no data).

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The specified format object is invalid.
sysErrBadIndex
The iterator value is invalid or past the last item in the set.

MMFormatGetTerm Function ^TOP^

Purpose

Returns the value of a term in a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatGetTerm (
   MMFormat format,
   const char *key,
   MMTypeCode typeCode,
   void *outValue,
   int32_t *ioLength
)

Parameters

format
A valid media format object.
key
Pointer to the key to search for.
typeCode
Pointer to the expected type of data. Specify one of the constants listed in "MMTypeCode."
outValue
On input, a pointer to a buffer capable of storing the specified type of data. On output, a pointer to the value, if it was found and enough storage space was provided.
ioLength
On input, if typeCode specifies a variable-length value with no delimiter (P_MM_TYPE_RAW,), then this is a pointer to the size of the outValue buffer in bytes; otherwise this may be NULL. On output, a pointer to the actual size of the value.

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The specified format object is invalid.
sysErrBadIndex
The specified key was not found.
sysErrBadType
The specified typeCode does not match the terms's type.
memErrNotEnoughSpace
The outValue buffer was filled to capacity with a partial value and ioLength is set to indicate the required capacity.

See Also

MMFormatGetTermInt32(), MMFormatGetTermType(), MMFormatSetTerm()

MMFormatGetTermInt32 Function ^TOP^

Purpose

Returns the value of a term in a media format object as an int32_t type.

Declared In

MMFormat.h

Prototype

status_t MMFormatGetTermInt32 (
   MMFormat format,
   const char *key,
   int32_t *outValue
)

Parameters

format
A valid media format object.
key
Pointer to the key to search for.
outValue
On input, a pointer to a buffer capable of storing the requested value. On output, a pointer to the value, if it was found and is representable as an int32_t (not a P_MM_TYPE_WILD, for example).

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The specified format object is invalid.
sysErrBadIndex
The specified key was not found.
sysErrBadType
The terms's value could not be converted to an int32_t.

See Also

MMFormatGetTerm()

MMFormatGetTermType Function ^TOP^

Purpose

Returns the type of a term in a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatGetTermType (
   MMFormat format,
   const char *key,
   MMTypeCode *outType
)

Parameters

format
A valid media format object.
key
Pointer to the key to find the type of.
outType
The term type.

Returns

The following result codes:

errNone
No error.
sysErrBadIndex
The specified key was not found.

See Also

MMFormatGetTerm()

MMFormatGetType Function ^TOP^

Purpose

Returns the type of a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatGetType (
   MMFormat format,
   MMFormatType *outType
)

Parameters

format
A valid media format object.
outType
The media format type.

Returns

errNone if the function was successful, otherwise an appropriate Multimedia Library error.

See Also

MMFormatSetType()

MMFormatRawAudio Function ^TOP^

Purpose

Returns the standard media format used to describe raw audio.

Declared In

MMFormat.h

Prototype

MMFormat MMFormatRawAudio (
   void
)

Parameters

None.

Returns

The standard media format used to describe raw audio.

See Also

MMFormatRawStill(), MMFormatRawVideo()

MMFormatRawStill Function ^TOP^

Purpose

Returns the standard media format used to describe a raw still image.

Declared In

MMFormat.h

Prototype

MMFormat MMFormatRawStill (
   void
)

Parameters

None.

Returns

The standard media format used to describe a raw still image.

See Also

MMFormatRawAudio(), MMFormatRawVideo()

MMFormatRawVideo Function ^TOP^

Purpose

Returns the standard media format used to describe raw video.

Declared In

MMFormat.h

Prototype

MMFormat MMFormatRawVideo (
   void
)

Parameters

None.

Returns

The standard media format used to describe raw video.

See Also

MMFormatRawAudio(), MMFormatRawStill()

MMFormatsCompatible Function ^TOP^

Purpose

Tests if two media format objects are compatible by matching their types and terms.

Declared In

MMFormat.h

Prototype

status_t MMFormatsCompatible (
   MMFormat a,
   MMFormat b
)

Parameters

a
A valid media format object.
b
A valid media format object.

Returns

The following result codes:

errNone
The formats are compatible.
mediaErrFormatMismatch
The formats are not compatible.
sysErrParamErr
One or both of the specified media formats has not been initialized.

MMFormatSetTerm Function ^TOP^

Purpose

Sets the value of a term in a media format object, replacing any existing value for the given key.

Declared In

MMFormat.h

Prototype

status_t MMFormatSetTerm (
   MMFormat format,
   const char *key,
   MMTypeCode typeCode,
   const void *value,
   int32_t length
)

Parameters

format
A valid media format object.
key
Pointer to the key to set the value for.
typeCode
The type of data provided in value.
value
Pointer to the value to set for the term identified by key.
length
If typeCode specifies a variable-length value with no delimiter (such as P_MM_TYPE_RAW), this parameter should indicate the size of the value in bytes. Otherwise, this parameter is ignored and should be set to 0.

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The specified media format is invalid.

See Also

MMFormatGetTerm()

MMFormatSetTermInt32 Function ^TOP^

Purpose

Sets the value of a term in a media format object to the specified int32_t value, replacing any existing value for the given key.

Declared In

MMFormat.h

Prototype

status_t MMFormatSetTermInt32 (
   MMFormat format,
   const char *key,
   int32_t value
)

Parameters

format
A valid media format object.
key
Pointer to the key to set the value for.
value
Pointer to the value to set for the term identified by key.

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The specified media format is invalid.

See Also

MMFormatGetTermInt32()

MMFormatSetType Function ^TOP^

Purpose

Changes the basic format type of a media format object.

Declared In

MMFormat.h

Prototype

status_t MMFormatSetType (
   MMFormat format,
   MMFormatType type
)

Parameters

format
A valid media format object.
type
The new type. Specify one of the constants listed in "formatType."

Returns

errNone if the function was successful, otherwise an appropriate Multimedia Library error.

See Also

MMFormatGetType()