Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Functions Used To Control Video Output Components
This section discusses the functions used to control video output components.
Controlling the Display Mode
Each video output device has a finite number of display modes. Each mode has several characteristics, including width and height of the display, pixel depth, and video refresh rate. This section describes functions for getting and setting the display mode.
To get a list of the display modes supported by a video output component, call the QTVideoOutputGetDisplayModeList
function. The list is a QT atom container, and list atoms contain the characteristics of each mode. You use QT atom container functions, such as QTFindChildByIndex
, to extract the contents of the list.
To specify a display mode to use, call the QTVideoOutputSetDisplayMode
function.
To find out the current display mode, call the QTVideoOutputGetDisplayMode
function.
Registering the Name of Your Software
After your software has established a connection to a video output component, you can register its name with the instance of that component by calling the QTVideoOutputSetClientName
function. The name can then be used by QTVideoOutputGetCurrentClientName
to specify which software has exclusive access to the video output device controlled by the component.
Although several applications or other software can connect to a video output component at the same time, only one of them at a time can have access to the video output device controlled by the component. Use QTVideoOutputBegin
to gain exclusive access to the video output device and QTVideoOutputEnd
to relinquish exclusive access when your software has finished using the device.
To get the name of the application or other software that is registered with an instance of a video output component, call QTVideoOutputGetClientName
.
Controlling Video Output
Video output components provide functions for configuring the video display, for starting and stopping video output, and for specifying the graphics world used for the display:
To display a dialog box in which the user can specify video settings, call the
QTVideoOutputGetConfigureDisplay
function.To get a pointer to the graphics world used by the video output component, call the
QTVideoOutputGetGWorld
function.To obtain exclusive access to the video hardware controlled by a video output component, call the
QTVideoOutputBegin
function.To release access to the video hardware controlled by a video output component, call the
QTVideoOutputEnd
function.To get the name of the software, if any, that has exclusive access to the video hardware controlled by a video output component, call the
QTVideoOutputGetCurrentClientName
function.If a video output device can display video both on an external video display and in a window on a computer’s desktop, you can use the
QTVideoOutputSetEchoPort
function to specify a window on the desktop in which to display video sent to the device.
Finding Associated Components
Video output components provide functions for finding other components associated with them:
To find any sound output components associated with a video output component, call the
QTVideoOutputGetIndSoundOutput
function.To find a clock component associated with a video output component, call the
QTVideoOutputGetClock
function.
Saving and Restoring Component Configurations
Video output components provide functions for saving the current configuration of a video output component and later restoring the configuration:
To save the current configuration of a video output component, call the
QTVideoOutputSaveState
function.To restore a previously saved configuration of a video output component, call the
QTVideoOutputRestoreState
function.
Data Types
This section describes the QT atom container used to specify the display modes that are supported by a video display component.
Display Mode QT Atom Container
The QTVideoOutputGetDisplayModeList
function returns a list of the display modes supported by a video display component. This list is contained in the QT atom container described in this section.
At the root of the QT atom container returned by the QTVideoOutputGetDisplayModeList
function are one or more atoms of type kQTVODisplayModeItem
, each containing a definition of a display mode. Your software can traverse the display mode atoms by calling the QTFindChildByIndex
function.
Within each kQTVODisplayModeItem
atom are the following atoms:
The atom of type
kQTVODimensions
with ID 1 contains two 32-bit integers. The first specifies the width, in pixels, of the display. The second specifies the height, in pixels, of the display.The atom of type
kQTVOResolution
with ID 1 contains two 32-bit fixed-point values. The first specifies the horizontal resolution of the display, in pixels per inch. The second specifies the vertical resolution of the display, in pixels per inch.
By storing resolutions rather than an aspect ratio, QuickTime makes it easy for your software to compare values with values in QuickTime ImageDescription
records. Your software can calculate the aspect ratio for the display mode by dividing the value for the horizontal resolution by the value for the vertical resolution.
The atom of type
kQTVORefreshRate
with ID 1 contains a single 32-bit fixed-point value. This value specifies the refresh rate of the display in Hertz.The atom of type
kQTVOPixelType
with ID 1 contains a single 32-bitOSType
value. This value specifies the type of pixel that is used by the display format:Values of 1, 2, 4, 8, 16, 24 and 32 specify standard Mac OS RGB pixel formats with corresponding bit depths.
Values of 33, 34, 36 and 40 specify standard Mac OS gray-scale pixel formats with depths of 1, 2, 4, and 8 bits per pixel.
Other pixel formats are specified by four-character codes. There are currently codes for RGB pixel formats defined for Microsoft Windows and for several YUV formats.
The atom of type
kQTVOName
with ID 1 contains a string that describes the display mode. Your software can use this string when presenting a list of available display modes to the user. The string does not include a leading length byte or a trailing null. Your software can determine the length of the string by getting the size of the atom that contains it.Atoms of type
kQTVODecompressors
specify any special decompressors that are required for the video output device. If a video output device cannot directly display 32-bit RGB data or data in one of the other supported QuickTime pixel formats, a special decompressor is required to convert images to data that the video output device can display.
Because kQTVODecompressors
atoms are not required to have consecutive IDs, your software must use the QTFindChildByIndex
function to iterate through the decompressors.
Within each kQTVODecompressors
atom are one or more atoms:
The atom of type
kQTVODecompressorType
with ID 1 contains anOSType
value that specifies the type of compressed data that the decompressor can decompress. For example, akQTVODecompressorType
atom that containskMotionJPEGACodecType
can decompress Motion JPEG Format A data.An atom of type
kQTVODecompressorComponent
with ID 1 is optional. If present, it contains aDecompressorComponent
value that specifies a decompressor component that your software can use to decompress the data specified by the correspondingkQTVODecompressorType
atom.An atom of type
kQTVODecompressorContinuous
with ID 1 is optional. If present, it contains a Boolean value that specifies whether the resulting video display will be continuous. If the value istrue
, data will be displayed without any visual gaps between successive images. If the value isfalse
, data will be displayed, but there may be a visual gap (such as a black screen) between the display of images. If there is nokQTVODecompressorContinuous
atom, your software should not make any assumptions about the performance of the decompressor.
Constants
This section provides details on component type, atom type, and function selector constants.
Component Instance, Type, and Subtype
typedef ComponentInstance QTVideoOutputComponent; |
enum { |
QTVideoOutputComponentType = FOUR_CHAR_CODE('vout'), |
QTVideoOutputComponentBaseSubType = FOUR_CHAR_CODE('base') |
}; |
Video Output Component Flag
The following flag indicates that a video output component is not connected to a display and should not be included in a list of components that are available to the user.
enum { |
kQTVideoOutputDontDisplayToUser = 1L << 0 |
}; |
Display Mode Atom Types
The following atom type constants specify atom types:
enum { |
kQTVODisplayModeItem = FOUR_CHAR_CODE('qdmi'), |
kQTVODimensions = FOUR_CHAR_CODE('dimn'), |
/* atom contains two longs - pixel count - width, height */ |
kQTVOResolution = FOUR_CHAR_CODE('resl'), |
/* atom contains two Fixed - hRes, vRes in dpi */ |
kQTVORefreshRate = FOUR_CHAR_CODE('refr'), |
/* atom contains one Fixed - refresh rate in Hz */ |
kQTVOPixelType = FOUR_CHAR_CODE('pixl'), |
/* atom contains one OSType - pixel format of mode */ |
kQTVOName = FOUR_CHAR_CODE('name'), |
/* atom contains string (no length byte) -- |
name of mode for display to user */ |
kQTVODecompressors = FOUR_CHAR_CODE('deco'), |
/* atom contains other atoms indicating supported decompressors */ |
/* kQTVODecompressors sub-atoms */ |
kQTVODecompressorType = FOUR_CHAR_CODE('dety'), |
/* atom contains one OSType - decompressor type code */ |
kQTVODecompressorContinuous = FOUR_CHAR_CODE('cont'), |
/* atom contains one Boolean -- |
true if this type is displayed continuously */ |
kQTVODecompressorComponent = FOUR_CHAR_CODE('cmpt') |
/* atom contains one component id of decompressor */ |
}; |
Copyright © 2005, 2006 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2006-01-10