Creating Video Digitizer Components

Video digitizer components are the most convenient mechanism for presenting new sources of video data to QuickTime. For example, if you are developing special-purpose video hardware that digitizes video images from a previously unsupported source device, you should create a video digitizer component so that applications or sequence grabber components can obtain data from your device.

Video digitizer components support a rich functional interface that can accommodate devices with quite varied capabilities. To relieve you from having to support irrelevant functions, Apple has made several video digitizer functions optional. For information about the functions your digitizer component must support, see Required Functions. For information about other functions, see Optional Functions.

Required Functions

At a minimum, your video digitizer component must support the following functions:

All of these functions are required for all video digitizer components.

Optional Functions

Based on the type of device your component supports, you may have to implement functions other than those listed in Required Functions and you may have to set some of your component’s capability flags. Read this section to learn which additional functions your component needs to support and how to set your capability flags properly.

If your component does not support a particular function, be sure to return a result code value of digiUnimpErr.

Frame Grabbers Without Playthrough

Suppose your video digitization hardware grabs frames but cannot simultaneously display the frames on the screen. Suppose also that your hardware supplies the grabbed frames in QuickDraw pixel maps at specific pixel depths (say, 16 and 32 bits per pixel).

In this case, you should set the following component capability flags:

Flag

Setting

digiOutDoes16

Set this flag to 1.

digiOutDoes32

Set this flag to 1. Set other depth flags to 0.

digiOutDoesHWPlayThru

Set this flag to 0.

digiOutDoesDMA

Set this flag to 0.

If your component can operate asynchronously, you should also set the following flag:

Flag

Setting

digiOutDoesAsyncGrabs

Set this flag to 1 if your component can operate asynchronously.

Frame grabbers that support asynchronous operation must support the following optional functions:

  • VDDone

  • VDGrabOneFrameAsync

  • VDReleaseAsyncBuffers

  • VDSetupBuffers

Frame Grabbers With Hardware Playthrough

If your frame grabber hardware provides support for playing the captured images directly, you need to support one additional function beyond those discussed in Frame Grabbers Without Playthrough. The VDSetPlayThruOnOff function allows the application to turn playthrough on and off.

You should also set the digiOutDoesHWPlayThru capability flag to 1. In addition, be sure to use the gdh field in the digitizer information structure to identify your component’s display device. For details on the video digitizer information structure, see The Digitizer Information Structure .

Key Color and Alpha Channel Devices

As a further elaboration on a basic frame grabber, your device could support the display or mixing of output data via an alpha channel or through the use of key colors (see Types of Video Digitizer Components for more information about alpha channels and key colors). In either case, image data cannot be read directly from the screen. Therefore, you must set the digiOutDoesUnreadableScreenBits capability flag to 1. For more on the video digitizer capability flags, see Capability Flags .

Your component must load its alpha channel or fill in the key color whenever playthrough is enabled or when the destination changes.

Compressed Source Devices

You may create a video digitizer component that supports a device that delivers compressed image data. In this case, your component is not capable of displaying the data directly.

Your component should set the following capability flags:

Flag

Setting

digiOutDoesCompress

Set this flag to 1.

digiOutDoesCompressOnly

Set this flag to 1 if your component cannot display the images directly.

digiOutDoesPlayThruDuringCompress

Set this flag to 1 if your component cannot display the images directly.

In addition, frame grabbers that support compressed source devices must support the following optional functions:

  • VDCompressDone

  • VDCompressOneFrameAsync

  • VDGetCompressionTypes

  • VDGetDataRate

  • VDGetImageDescription

  • VDResetCompressSequence

  • VDSetCompression

  • VDSetCompressionOnOff

  • VDSetFrameRate

  • VDSetTimeBase

If your hardware generates compressed data that cannot be decompressed by any standard QuickTime image decompressor components, be sure to provide an appropriate decompressor component so that the data you provide can be displayed.

Function Request Codes

You can use the following enumerators to refer to the request codes for each of the functions that your component must support.

enum {
    kSelectVDGetMaxSrcRect           = 0x1,  /* VDGetMaxSrcRect (required) */
    kSelectVDGetActiveSrcRect        = 0x2,  /* VDGetActiveSrcRect
                                                                (required) */
    kSelectVDSetDigitizerRect        = 0x3,  /* VDSetDigitizerRect
                                                                (required) */
    kSelectVDGetDigitizerRect        = 0x4,  /* VDGetDigitizerRect
                                                                (required) */
    kSelectVDGetVBlankRect           = 0x5,  /* VDGetVBlankRect (required) */
    kSelectVDGetMaskPixMap               = 0x6,  /* VDGetMaskPixMap */
    kSelectVDGetPlayThruDestination      = 0x8,  /* VDGetPlayThruDestination
                                                                (required) */
    kSelectVDUseThisCLUT                 = 0x9,  /* VDUseThisCLUT */
    kSelectVDSetInputGammaValue          = 0xA,  /* VDSetInputGammaValue */
    kSelectVDGetInputGammaValue          = 0xB,  /* VDGetInputGammaValue */
    kSelectVDSetBrightness               = 0xC,  /* VDSetBrightness */
    kSelectVDGetBrightness               = 0xD,  /* VDGetBrightness */
    kSelectVDSetContrast                 = 0xE,  /* VDSetContrast */
    kSelectVDSetHue                      = 0xF,  /* VDSetHue */
    kSelectVDSetSharpness                = 0x10, /* VDSetSharpness */
    kSelectVDSetSaturation               = 0x11, /* VDSetSaturation */
    kSelectVDGetContrast                 = 0x12, /* VDGetContrast */
    kSelectVDGetHue                      = 0x13, /* VDGetHue */
    kSelectVDGetSharpness                = 0x14,/* VDGetSharpness */
    kSelectVDGetSaturation               = 0x15, /* VDGetSaturation */
    kSelectVDGrabOneFrame                = 0x16, /* VDGrabOneFrame
                                                                (required) */
    kSelectVDGetMaxAuxBuffer             = 0x17, /* VDGetMaxAuxBuffer */
    kSelectVDGetDigitizerInfo            = 0x19, /* VDGetDigitizerInfo
                                                                (required) */
    kSelectVDGetCurrentFlags             = 0x1A, /* VDGetCurrentFlags
                                                                (required) */
    kSelectVDSetKeyColor                 = 0x1B, /* VDSetKeyColor */
    kSelectVDGetKeyColor                 = 0x1C, /* VDGetKeyColor */
    kSelectVDAddKeyColor                 = 0x1D, /* VDAddKeyColor */
    kSelectVDGetNextKeyColor             = 0x1E, /* VDGetNextKeyColor */
    kSelectVDSetKeyColorRange            = 0x1F, /* VDSetKeyColorRange */
    kSelectVDGetKeyColorRange            = 0x20, /* VDGetKeyColorRange */
    kSelectVDSetDigitizerUserInterrupt   = 0x21,
                                              /* VDSetDigitizerUserInterrupt */
    kSelectVDSetInputColorSpaceMode      = 0x22, /* VDSetInputColorSpaceMode */
    kSelectVDGetInputColorSpaceMode      = 0x23, /* VDGetInputColorSpaceMode */
    kSelectVDSetClipState                = 0x24, /* VDSetClipState */
    kSelectVDSetClipState                = 0x25, /* VDGetClipState */
    kSelectVDSetClipRgn                  = 0x26, /* VDSetClipRgn */
    kSelectVDClearClipRgn                = 0x27, /* VDClearClipRgn */
    kSelectVDGetCLUTInUse                = 0x28, /* VDGetCLUTInUse */
    kSelectVDSetPLLFilterType            = 0x29, /* VDSetPLLFilterType */
    kSelectVDGetPLLFilterType            = 0x2A, /* VDGetPLLFilterType */
    kSelectVDGetMaskandValue             = 0x2B, /* VDGetMaskandValue */
    kSelectVDSetMasterBlendLevel         = 0x2C, /* VDSetMasterBlendLevel */
    kSelectVDSetPlayThruDestination      = 0x2D, /* VDSetPlayThruDestination */
    kSelectVDSetPlayThruOnOff            = 0x2E, /* VDSetPlayThruOnOff */
    kSelectVDSetFieldPreference          = 0x2F, /* VDSetFieldPreference
                                                                (required) */
    kSelectVDGetFieldPreference          = 0x30, /* VDGetFieldPreference
                                                                (required) */
    kSelectVDPreflightDestination        = 0x32, /* VDPreflightDestination
                                                                (required) */
    kSelectVDPreflightGlobalRect         = 0x33, /* VDPreflightGlobalRect */
    kSelectVDSetPlayThruGlobalRect       = 0x34, /* VDSetPlayThruGlobalRect */
    kSelectVDSetInputGammaRecord         = 0x35, /* VDSetInputGammaRecord */
    kSelectVDGetInputGammaRecord         = 0x36, /* VDGetInputGammaRecord */
    kSelectVDSetBlackLevelValue          = 0x37,/* VDSetBlackLevelValue */
    kSelectVDGetBlackLevelValue          = 0x38, /* VDGetBlackLevelValue */
    kSelectVDSetWhiteLevelValue          = 0x39, /* VDSetWhiteLevelValue */
    kSelectVDGetWhiteLevelValue          = 0x3A, /* VDGetWhiteLevelValue */
    kSelectVDGetVideoDefaults            = 0x3B, /* VDGetVideoDefaults */
    kSelectVDGetNumberOfInputs           = 0x3C,/* VDGetNumberOfInputs */
    kSelectVDGetInputFormat              = 0x3D, /* VDGetInputFormat */
    kSelectVDSetInput                    = 0x3E, /* VDSetInput */
    kSelectVDGetInput                    = 0x3F, /* VDGetInput */
    kSelectVDSetInputStandard            = 0x40, /* VDSetInputStandard */
    kSelectVDSetupBuffers                = 0x41, /* VDSetupBuffers */
    kSelectVDGrabOneFrameAsync           = 0x42, /* VDGrabOneFrameAsync */
    kSelectVDDone                        = 0x43, /* VDDone */
    kSelectVDSetCompression              = 0x44, /* VDSetCompression */
    kSelectVDCompressOneFrameAsync       = 0x45, /* VDCompressOneFrameAsync */
    kSelectVDCompressDone                = 0x46, /* VDCompressDone */
    kSelectVDReleaseCompressBuffer       = 0x47, /* VDReleaseCompressBuffer */
    kSelectVDGetImageDescription         = 0x48, /* VDGetImageDescription */
    kSelectVDResetCompressSequence       = 0x49, /* VDResetCompressSequence */
    kSelectVDSetCompressionOnOff         = 0x4A, /* VDSetCompressionOnOff */
    kSelectVDGetCompressionTypes         = 0x4B, /* VDGetCompressionTypes */
    kSelectVDSetTimeBase                 = 0x4C, /* VDSetTimeBase */
    kSelectVDSetFrameRate                = 0x4D, /* VDSetFrameRate */
    kSelectVDGetDataRate                 = 0x4E, /* VDGetDataRate */
    kSelectVDGetSoundInputDriver         = 0x4F, /* VDGetSoundInputDriver */
    kSelectVDGetDMADepths                = 0x50, /* VDGetDMADepths */
    kSelectVDGetPreferredTimeScale       = 0x51, /* VDGetPreferredTimeScale */
    kSelectVDReleaseAsyncBuffers         = 0x52,/* VDReleaseAsyncBuffers */
};


Copyright © 2005, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01