Retired Document
Important: This document contains legacy content. Apple recommends that developers explore AV Foundation and Core Video for new development in this technology area. See AV Foundation Framework Reference for Mac and Core Video Programming Guide for more information.
Video Digitizer Component API
Introduction
This chapter describes the functions that are provided by video digitizer components. These functions are described from the perspective of an application that uses video digitizer components. If you are developing a video digitizer component, your digitizer component must behave as described here.
These functions specify the video digitizer components for their requests with a reference obtained from the Component Manager’s OpenComponent
or OpenAComponent
function.
Component Type and Subtype Values
Apple has defined a type value for video digitizer components. All video digitizer components have a component type value of 'vdig'
. You can use the following constant to specify the component type value.
#define videoDigitizerComponentType = 'vdig' |
There are no special conventions applied to the subtype value of video digitizer components.
Getting Information About Video Digitizer Components
You can use the VDGetDigitizerInfo
function in your application to retrieve information about the capabilities of a video digitizer component. You can use the VDGetCurrentFlags
function to obtain current status information from a video digitizer component.
Setting Source Characteristics
This section discusses the video digitizer component functions that allow applications to set the spatial characteristics of the source video signal. You can use these functions in your application to set and retrieve information about the maximum source rectangle, the active source rectangle, the vertical blanking rectangle, and the digitizer rectangle. For a complete discussion of the relationship between these rectangles, see About Video Digitizer Components.
You can use the VDGetMaxSrcRect
function in your application to get the size and location of the maximum source rectangle. Similarly, the VDGetActiveSrcRect
function allows you to get this information about the active source rectangle, and the VDGetVBlankRect
function enables you to obtain information about the vertical blanking rectangle.
You can use the VDSetDigitizerRect
function to set the size and location of the digitizer rectangle. The VDGetDigitizerRect
function lets you retrieve the size and location of this rectangle.
Selecting an Input Source
This section discusses the video digitizer component functions that allow applications to select an input video source.
Some of these functions provide information about the available video inputs. Applications can use the VDGetNumberOfInputs
function to determine the number of video inputs supported by the digitizer component. The VDGetInputFormat
function allows applications to find out the video format (composite, s-video, or component) employed by a specified input.
You can use the VDSetInput
function in your application to specify the input to be used by the digitizer component. The VDGetInput
function returns the currently selected input.
The VDSetInputStandard
function allows you to specify the video signaling standard to be used by the video digitizer component.
Controlling Color
Video digitizer components support color digitization. Therefore, these components provide several functions that allow applications to control the color digitization process.
You can use VDSetInputColorSpaceMode
in your application to enable and disable color digitization; you can use the VDGetInputColorSpaceMode
function to determine whether color digitization is enabled. The VDUseThisCLUT
function allows you to specify a color lookup table to be used by the video digitizer component. In cases where the component cannot accommodate a particular lookup table, your application can use the VDGetCLUTInUse
function to retrieve the color lookup table used by the digitizer component.
Your application can determine whether a digitizer component supports color digitization by examining the input capability flags of the component. Specifically, if the digiInDoesColor
flag is set to 1, the component supports color digitization. Applications can use the VDGetCurrentFlags
function to obtain the input capability flags of a component. See Getting Information About Video Digitizer Components for more information.
Your application can determine a digitizer’s supported pixel depths by calling the VDGetDMADepths
function.
Controlling Analog Video
Some video digitizer components may provide functions that allow applications to control the characteristics of the input analog video signal. This section describes these analog video functions.
The VDGetVideoDefaults
function returns the suggested default values for the analog video parameters that can be affected by functions described in this section.
A number of functions affect gamma correction. The VDSetInputGammaRecord
and VDGetInputGammaRecord
functions work with gamma structures. You can use the VDSetInputGammaValue
and VDGetInputGammaValue
functions to allow your application to set particular gamma values.
The VDSetBlackLevelValue
, VDGetBlackLevelValue
, VDSetWhiteLevelValue
, and VDGetWhiteLevelValue
functions allow applications to work with black levels and white levels in the source video. Black level refers to the degree of blackness in an image. This is a common setting on a video digitizer. The highest setting produces an all-black image; on the other hand, the lowest setting yields little, if any, black even with black objects in the scene. Black level is a significant setting because it can be adjusted so that there is little or no noise in an image. White level refers to the degree of whiteness in an image. It is also a common video digitizer setting.
The VDSetContrast
, VDGetContrast
, VDSetSharpness
, and VDGetSharpness
functions allow applications to work with contrast and sharpness values in the source video. The VDGetBrightness
and VDSetBrightness
functions allow applications to work with the image brightness setting.
The VDSetHue
, VDGetHue
, VDSetSaturation
, and VDGetSaturation
functions allow applications to work with hue and saturation settings in the source video.
Selectively Displaying Video
Video digitizer components may support one of three methods of selectively displaying video on the computer screen. The three methods are key colors, alpha channels, and blend masks. For a complete description of these techniques for selectively displaying video, see About Video Digitizer Components.
Your application can determine whether a video digitizer component supports selective video display by examining the component’s digitizer information structure. Specifically, the vdigType
field indicates the type of blending supported by the digitizer. Applications can use the VDGetDigitizerInfo
function to retrieve a component’s digitizer information structure.
Some video digitizer components support the use of key colors as a mechanism for selectively displaying video on the computer screen. When a key color is active, the digitizer component replaces all screen occurrences of that color with the appropriate portion of the source video. Video digitizer components that support key colors provide a number of functions to applications. Those functions are described in this section.
Your applications can use the VDSetKeyColor
, VDAddKeyColor
, and VDSetKeyColorRange
functions to set one or more key colors for a video digitizer component. The VDGetKeyColor
, VDGetNextKeyColor
, and VDGetKeyColorRange
functions allow your application to retrieve information about the currently active key colors.
Alpha channels and blend masks work similarly to one another. Digitizer components that support alpha channels use a portion of each pixel value to indicate the degree of video display for that pixel. Digitizer components that support blend masks use the mask to indicate the degree of video display for corresponding pixels.
Your applications can use the VDGetMaskandValue
function to determine the appropriate mask value for a desired blend level. The VDSetMasterBlendLevel
function allows applications to set a blend level that applies to the entire source video image. The VDGetMaskPixMap
function allows applications to retrieve the pixel map that defines the blend mask.
Clipping
Some video digitizer components can clip the output video image based on an arbitrary clipping region. Your application can determine whether a video digitizer component supports clipping by examining the digitizer information structure of the component. Specifically, if the digiOutDoesMask
flag is set to 1 in the outputCapabilityFlags
field of the appropriate digitizer information structure, the component supports clipping. See The Digitizer Information Structure for details. Your application can obtain a component’s digitizer information structure by calling the VDGetDigitizerInfo
function. This section describes the functions provided to applications by components that support clipping.
Applications can use the VDSetClipState
and VDGetClipState
functions to enable and disable clipping, and to determine whether clipping is enabled. Applications can use the VDSetClipRgn
and VDClearClipRgn
functions to manipulate the clipping region. Applications can use these functions only during an active grab sequence. Applications set the initial clipping settings by calling either VDSetPlayThruDestination
or VDSetPlayThruGlobalRect
.
Utility Functions
A number of utility functions may be supported by some video digitizer components:
The
VDSetPLLFilterType
andVDGetPLLFilterType
functions allow applications to control which phase-locked loop (PLL) is used by a video digitizer component that supports multiple PLLs.The
VDSetFieldPreference
andVDGetFieldPreference
functions allow applications to control which field is used for some vertical scaling operations.The
VDSetDigitizerUserInterrupt
function allows applications to install custom interrupt functions that are called by the video digitizer component.The
VDGetSoundInputDriver
function allows an application to retrieve information about a digitizer’s sound input driver.The
VDGetPreferredTimeScale
function allows an application to determine a digitizer’s preferred time scale.The
VDGetTimeCode
function allows an application to retrieve timecode information.
The
VDGetSoundInputSource
function allows an application to retrieve information about a digitizer’s sound input source.Video digitizers may return timecode information for an incoming video signal by responding to
VDGetTimeCode
.You can use the
VDGetInputFormat
function to find out the video format employed by a specified input.
Application-Defined Function
Applications can provide a custom interrupt function in the userInterruptProc
parameter of the VDSetDigitizerUserInterrupt
function. Every custom interrupt function must support the following interface:
pascal void MyInterruptProc (long flags, long refcon); |
The flags
parameter indicates when the interrupt function has been called. The video digitizer component sets these flags to indicate the circumstances in which the function has been called. The following flags are defined:
Flag |
Description |
---|---|
|
Even-line field interrupt. If this flag is set to 1, the video digitizer component is about to display an even-line field. |
|
Odd-line field interrupt. If this flag is set to 1, the video digitizer component is about to display an odd-line field. |
The refcon
parameter contains parameter data that is appropriate for the interrupt function. The application assigns the value of the reference constant when it sets the interrupt function.
Capability Flags
Video digitizer components report their capabilities to your application by means of capability flags. These flags are formatted as part of the digitizer information structure you obtain by calling the VDGetDigitizerInfo
function. There are two sets of flags: one set describes the input capabilities of the video digitizer component, and the other describes its output capabilities.
Video digitizer components support the following input capability flags:
Flag |
Description |
---|---|
|
Indicates that the video digitizer supports National Television System Committee (NTSC) format input video signals. This flag is set to 1 if the digitizer component supports NTSC video. |
|
Indicates that the video digitizer component supports Phase Alternation Line (PAL) format input video signals. This flag is set to 1 if the digitizer component supports PAL video. |
|
Indicates that the video digitizer component supports Systeme Electronique Couleur avec Memoire (SECAM) format input video signals. This flag is set to 1 if the digitizer component supports SECAM video. |
|
Indicates that the video digitizer component supports genlock; that is, the digitizer can derive its timing from an external time base. This flag is set to 1 if the digitizer component supports genlock. |
|
Indicates that the video digitizer component supports composite input video. This flag is set to 1 if the digitizer component supports composite input. |
|
Indicates that the video digitizer component supports s-video input video. This flag is set to 1 if the digitizer component supports s-video input. |
|
Indicates that the video digitizer component supports RGB input video. This flag is set to 1 if the digitizer component supports RGB input. |
|
Indicates that the video digitizer component can distinguish between an input signal that emanates from a videotape player and a broadcast signal. This flag is set to 1 if the digitizer component can differentiate between the two different signal types. |
|
Indicates that the video digitizer component supports color input. This flag is set to 1 if the digitizer component can accept color input. |
|
Indicates that the video digitizer component supports grayscale input. This flag is set to 1 if the digitizer component can accept grayscale input. |
Video digitizer components support the following output capability flags:
Flag |
Description |
---|---|
|
Indicates that the video digitizer component can work with pixel maps that contain 1-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 1-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component can work with pixel maps that contain 2-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 2-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component can work with pixel maps that contain 4-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 4-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component can work with pixel maps that contain 8-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 8-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component can work with pixel maps that contain 16-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 16-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component can work with pixel maps that contain 32-bit pixels. If this flag is set to 1, then the digitizer component can write images that contain 32-bit pixels. If this flag is set to 0, then the digitizer component cannot handle such images. |
|
Indicates that the video digitizer component supports dithering. If this flag is set to 1, the component supports dithering of colors. If this flag is set to 0, the digitizer component does not support dithering. |
|
Indicates that the video digitizer component can stretch images to arbitrary sizes. If this flag is set to 1, the digitizer component can stretch images. If this flag is set to 0, the digitizer component does not support stretching. |
|
Indicates that the video digitizer component can shrink images to arbitrary sizes. If this flag is set to 1, the digitizer component can shrink images. If this flag is set to 0, the digitizer component does not support shrinking. |
|
Indicates that the video digitizer component can handle clipping regions. If this flag is set to 1, the digitizer component can mask to an arbitrary clipping region. If this flag is set to 0, the digitizer component does not support clipping regions. |
|
Indicates that the video digitizer component supports stretching to quadruple size when displaying the output video. The parameters for the stretch operation are specified in the matrix structure for the request; the component modifies the scaling attributes of the matrix. If this flag is set to 1, the digitizer component can stretch an image to exactly four times its original size, up to the maximum size specified by the |
|
Indicates that the video digitizer component supports stretching an image to 16 times its original size when displaying the output video. The parameters for the stretch operation are specified in the matrix structure for the request; the component modifies the scaling attributes of the matrix. If this flag is set to 1, the digitizer component can stretch an image to exactly 16 times its original size, up to the maximum size specified by the |
|
Indicates that the video digitizer component can shrink an image to one-quarter of its original size when displaying the output video. The parameters for the shrink operation are specified in the matrix structure for the request; the component modifies the scaling attributes of the matrix. If this flag is set to 1, the digitizer component can shrink an image to exactly one-quarter of its original size, down to the minimum size specified by the |
|
Indicates that the video digitizer component can shrink an image to 1/16 of its original size when displaying the output video. The parameters for the shrink operation are specified in the matrix structure for the request; the digitizer component modifies the scaling attributes of the matrix. If this flag is set to 1, the digitizer component can shrink an image to exactly 1/16 of its original size, down to the minimum size specified by the |
|
Indicates that the video digitizer component can rotate an image when displaying the output video. The parameters for the rotation are specified in the matrix structure for an operation. If this flag is set to 1, the digitizer component can rotate the image. If this flag is set to 0, the digitizer component cannot rotate the resulting image. |
|
Indicates that the video digitizer component can flip an image horizontally when displaying the output video. The parameters for the horizontal flip are specified in the matrix structure for an operation. If this flag is set to 1, the digitizer component can flip the image. If this flag is set to 0, the digitizer component cannot flip the resulting image. |
|
Indicates that the video digitizer component can flip an image vertically when displaying the output video. The parameters for the vertical flip are specified in the matrix structure for an operation. If this flag is set to 1, the digitizer component can flip the image. If this flag is set to 0, the digitizer component cannot flip the resulting image. |
|
Indicates that the video digitizer component can skew an image when displaying the output video. Skewing an image distorts it linearly along only a single axis; for example, drawing a rectangular image into a parallelogram-shaped region. The parameters for the skew operation are specified in the matrix structure for the request. If this flag is set to 1, the digitizer component can skew an image. If this flag is set to 0, the digitizer component does not support this capability. |
|
Indicates that the video digitizer component can blend the resulting image with a matte when displaying the output video. The matte is provided by the application by defining either an alpha channel or a mask plane. If this flag is set to 1, the digitizer component can blend. If this flag is set to 0, the digitizer component does not support this capability. |
|
Indicates that the video digitizer component can warp an image when displaying the output video. Warping an image distorts it along one or more axes, perhaps nonlinearly, in effect "bending" the result region. The parameters for the warp operation are specified in the matrix structure for the request. If this flag is set to 1, the digitizer component can warp an image. If this flag is set to 0, the digitizer component does not support this capability. |
|
Indicates that the video digitizer component can write to any screen or to offscreen memory. If this flag is set to 1, the digitizer component can use DMA to write to any screen or memory location. |
|
Indicates that the video digitizer component does not need idle time in order to display its video. If this flag is set to 1, your application does not need to grant processor time to the digitizer component at normal display speeds. |
|
Indicates that the video digitizer component supports inverse lookup tables for indexed color modes. If this flag is set to 1, the digitizer component uses inverse lookup tables when appropriate. |
|
Indicates that the video digitizer component supports clipping by means of key colors. If this flag is set to 1, the digitizer component can clip to a region defined by a key color. |
|
Indicates that the video digitizer component can operate asynchronously. If this flag is set to 1, your application can use the |
|
Indicates that the video digitizer may place pixels on the screen that cannot be used when compressing images. |
|
Indicates that the video digitizer component supports compressed source devices. These devices provide compressed data directly, without having to use the Image Compression Manager. |
|
Indicates that the video digitizer component only provides compressed image data; the component cannot provide displayable data. This flag only applies to digitizers that support compressed source devices. |
|
Indicates that the video digitizer component can draw images on the screen at the same time that it is delivering compressed image data. This flag only applies to digitizers that support compressed source devices. |
Data Types
This section discusses the data structures that are used by video digitizer components and by applications that use video digitizer components.
The Digitizer Information Structure
Your application can retrieve information about the capabilities and current status of a video digitizer component. You call the VDGetDigitizerInfo
function to retrieve all this information from a video digitizer component. In response, the component formats a digitizer information structure. The contents of this structure fully define the capabilities and current status of the video digitizer component.
The DigitizerInfo
data type defines the layout of the digitizer information structure:
struct DigitizerInfo { |
short vdigType; |
long inputCapabilityFlags; |
long outputCapabilityFlags; |
long inputCurrentFlags; |
long outputCurrentFlags; |
short slot; |
GDHandle gdh; |
GDHandle maskgdh; |
short minDestHeight; |
short minDestWidth; |
short maxDestHeight; |
short maxDestWidth; |
short blendLevels; |
long reserved; |
}; |
Field |
Description |
---|---|
|
Specifies the type of video digitizer component. Valid values are listed below. |
|
Specifies the capabilities of the video digitizer component with respect to the input video signal. |
|
Specifies the capabilities of the video digitizer component with respect to the output digitized video information. |
|
Specifies the current status of the video digitizer with respect to the input video signal. |
|
Specifies the current status of the video digitizer with respect to the output digitized video information. |
|
Identifies the slot that contains the video digitizer interface card. |
|
Contains a handle to the graphics device that defines the screen to which the digitized data is to be written. Set this field to |
|
Contains a handle to the graphics device that contains the mask plane. This field is used only by digitizers that clip by means of mask planes. |
|
Indicates the smallest height value the digitizer component can accommodate in its destination. |
|
Indicates the smallest width value the digitizer component can accommodate in its destination. |
|
Indicates the largest height value the digitizer component can accommodate in its destination. |
|
Indicates the largest width value the digitizer component can accommodate in its destination. |
|
Specifies the number of blend levels the video digitizer component supports. |
|
Reserved. Set this field to 0. |
The inputCapabilityFlags
and outputCapabilityFlags
values are listed in Capability Flags.
The vdigType
field may contain these values:
Constant |
Description |
---|---|
|
Basic video digitizer; does not support any clipping |
|
Supports clipping by means of an alpha channel |
|
Supports clipping by means of a mask plane |
|
Supports clipping by means of key colors |
The Buffer List Structure
If you are using more than one asynchronous output buffer, you must define the output buffers to the video digitizer component. You define these output buffers by calling the VDSetupBuffers
function. You specify the buffers to that function in a buffer list structure. Note that all the output buffers must be the same size and must accommodate output rectangles of the same dimensions.
The VdigBufferRecList
data type defines a buffer list structure.
struct VdigBufferRecList { |
short count; |
MatrixRecordPtr matrix; |
RgnHandle mask; |
VdigBufferRec list[1]; |
}; |
Field |
Description |
---|---|
|
Specifies the number of buffers defined by this structure. The value of this field must correspond to the number of entries in the |
|
Specifies the transformation matrix that is applied to all of the destination rectangles before the video image is displayed. You must specify a matrix. If you do not want to perform any transformations, use the identity matrix. |
|
Specifies a clipping region that is applied to the destination rectangle before the video image is displayed. Note that this region applies to only the first destination buffer. If you want the region to apply to all of your destination buffers, you must do this yourself. If you do not want to specify a clipping region, set this field to |
|
Contains an array of output buffer specifications. Each buffer is represented by a buffer structure. The format and content of this structure are described in the next section. |
The Buffer Structure
The VdigBufferRec
data type defines a buffer structure.
typedef struct { |
PixMapHandle dest; |
Point location; |
long reserved; |
} VdigBufferRec; |
Field |
Description |
---|---|
|
Contains a handle to the pixel map that defines the destination buffer. |
|
Specifies the location of the video destination in the pixel map specified by the |
|
Reserved for use by Apple. Set this field to 0. |
Copyright © 2005, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01