Next Previous

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 and VDGetPLLFilterType functions allow applications to control which phase-locked loop (PLL) is used by a video digitizer component that supports multiple PLLs.
The VDSetFieldPreference and VDGetFieldPreference 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
`Bit` `0`	Even-line field interrupt. If this flag is set to 1, the video digitizer component is about to display an even-line field.
`Bit` `1`	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
`digiInDoesNTSC`	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.
`digiInDoesPAL`	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.
`digiInDoesSECAM`	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.
`digiInDoesGenLock`	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.
`digiInDoesComposite`	Indicates that the video digitizer component supports composite input video. This flag is set to 1 if the digitizer component supports composite input.
`digitInDoesSVideo`	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.
`digiInDoesComponent`	Indicates that the video digitizer component supports RGB input video. This flag is set to 1 if the digitizer component supports RGB input.
`digiInVTR_Broadcast`	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.
`digiInDoesColor`	Indicates that the video digitizer component supports color input. This flag is set to 1 if the digitizer component can accept color input.
`digiInDoesBW`	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
`digiOutDoes1`	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.
`digiOutDoes2`	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.
`digiOutDoes4`	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.
`digiOutDoes8`	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.
`digiOutDoes16`	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.
`digiOutDoes32`	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.
`digiOutDoesDither`	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.
`digiOutDoesStretch`	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.
`digiOutDoesShrink`	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.
`digiOutDoesMask`	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.
`digiOutDoesDouble`	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 `maxDestHeight` and `maxDestWidth` fields in the digitizer information structure. If this flag is set to 0, the digitizer component does not support stretching to quadruple size.
`digiOutDoesQuad`	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 `maxDestHeight` and `maxDestWidth` fields in the digitizer information structure. If this flag is set to 0, the digitizer component does not support this capability.
`digiOutDoesQuarter`	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 `minDestHeight` and `minDestWidth` fields in the digitizer information structure. If this flag is set to 0, the digitizer component does not support this capability.
`digiOutDoesSixteenth`	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 `minDestHeight` and `minDestWidth` fields in the digitizer information structure. If this flag is set to 0, the digitizer component does not support this capability.
`digiOutDoesRotate`	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.
`digiOutDoesHorizFlip`	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.
`digiOutDoesVertFlip`	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.
`digiOutDoesSkew`	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.
`digiOutDoesBlend`	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.
`digiOutDoesWarp`	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.
`digiOutDoesDMA`	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.
`digiOutDoesHWPlayThru`	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.
`digiOutDoesILUT`	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.
`digiOutDoesKeyColor`	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.
`digiOutDoesAsyncGrabs`	Indicates that the video digitizer component can operate asynchronously. If this flag is set to 1, your application can use the `VDSetupBuffers` and `VDGrabOneFrameAsync` functions.
`digiOutDoesUnreadableScreenBits`	Indicates that the video digitizer may place pixels on the screen that cannot be used when compressing images.
`digiOutDoesCompress`	Indicates that the video digitizer component supports compressed source devices. These devices provide compressed data directly, without having to use the Image Compression Manager.
`digiOutDoesCompressOnly`	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.
`digiOutDoesPlayThruDuringCompress`	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
`vdigType`	Specifies the type of video digitizer component. Valid values are listed below.
`inputCapabilityFlags`	Specifies the capabilities of the video digitizer component with respect to the input video signal.
`outputCapabilityFlags`	Specifies the capabilities of the video digitizer component with respect to the output digitized video information.
`inputCurrentFlags`	Specifies the current status of the video digitizer with respect to the input video signal.
`outputCurrentFlags`	Specifies the current status of the video digitizer with respect to the output digitized video information.
`slot`	Identifies the slot that contains the video digitizer interface card.
`gdh`	Contains a handle to the graphics device that defines the screen to which the digitized data is to be written. Set this field to `nil` if your application is not constrained to a particular graphics device.
`maskgdh`	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.
`minDestHeight`	Indicates the smallest height value the digitizer component can accommodate in its destination.
`minDestWidth`	Indicates the smallest width value the digitizer component can accommodate in its destination.
`maxDestHeight`	Indicates the largest height value the digitizer component can accommodate in its destination.
`maxDestWidth`	Indicates the largest width value the digitizer component can accommodate in its destination.
`blendLevels`	Specifies the number of blend levels the video digitizer component supports.
`reserved`	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
`vdTypeBasic`	Basic video digitizer; does not support any clipping
`vdTypeAlpha`	Supports clipping by means of an alpha channel
`vdTypeMask`	Supports clipping by means of a mask plane
`vdTypeKey`	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
`count`	Specifies the number of buffers defined by this structure. The value of this field must correspond to the number of entries in the `list` array.
`matrix`	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.
`mask`	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 `nil`.
`list`	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
`dest`	Contains a handle to the pixel map that defines the destination buffer.
`location`	Specifies the location of the video destination in the pixel map specified by the `dest` field. This point identifies the upper-left corner of the destination rectangle. The size and scaling of the destination rectangle are governed by the `matrix` and `mask` fields of the buffer list structure that contains this structure.
`reserved`	Reserved for use by Apple. Set this field to 0.

Next Previous