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.

Using Sequence Grabber Channel Components

This chapter gives an overview of the services your channel component needs to provide. Your component will primarily be used to preview and record digital data. Your component must also make calls to application-defined callback functions if so directed. Finally, your component must provide utility functions that will perform default procedures for the application’s callback functions.

In response to application requests, sequence grabber components can use channel components in two ways: to preview digitized data for the user or to record captured data in a QuickTime movie. Applications can use previewing to allow the user to prepare to make a recording. Applications that use previewing can move directly from the preview operation to a record operation, without stopping the process.

The next two sections provide an overview of preview and record operations. A third section discusses the callback functions that are supported by some channel components.

Previewing

Previewing captured data involves playing that data for the user as it is digitized. For video data, this means displaying the video images on the computer screen. For audio data, this means playing the sound through the computer’s sound system. The following paragraphs outline the steps the sequence grabber component follows to preview captured data.

First, the sequence grab ber component opens a connection to your channel component, using the Component Manager’s OpenComponent function. The sequence grabber component then calls your SGInitChannel function to initialize your component.
The sequence grabber component then configures your channel component for the preview operation. The SGSetGWorld function sets the graphics world in which the preview is to be displayed. The SGSetChannelUsage function specifies that your channel is to be used for previewing. The application can then use the appropriate channel configuration functions to prepare your channel for the preview operation. For video channels, it uses the functions discussed in Configuration Functions for Video Channel Components. For sound channels, the sequence grabber uses the functions discussed in Configuration Functions for Sound Channel Components.
The sequence grabber component starts the preview operation by calling your SGStartPreview function. The sequence grabber component then begins collecting data from all of the channels participating in the preview and plays that data appropriately. The sequence grabber component can pause and restart the preview by calling the SGPause function. The sequence grabber component uses the SGStop function to stop the preview. During the preview operation, the sequence grabber component calls your SGIdle function frequently, so that your channel can perform its operation.
When the application is done previewing, the sequence grabber component can start recording or close its connection to your component.

The following functions allow sequence grabber components to control your channel component:

SGStartPreview
SGStartRecord
SGIdle
SGUpdate
SGStop
SGWriteSamples
SGPause
SGPrepare
SGRelease

Configuring Sequence Grabber Channel Components

This section discusses the functions that allow sequence grabber components to configure your channel component.

Sequence grabber components use a number of functions to establish the environment for grabbing or previewing digitized data. This section describes the channel component functions that allow the sequence grabber component to establish the environment for recording or previewing captured data.

The sequence grabber component uses the SGInitChannel function to initialize your channel prior to a record or preview operation.

The SGSetGWorld function allows the sequence grabber component to assign a graphics world to your component.

Configuration Functions for All Channel Components

Your channel is assigned to a sequence grabber component when the application calls the sequence grabber component’s SGNewChannel function, described in the chapter Sequence Grabber Component Functions in this document. The sequence grabber component must configure your channel before a preview or record operation. Your channel component must provide a number of functions that allow the sequence grabber to configure the characteristics of your channel. Several of these functions work on any channel component. This section discusses these general channel configuration functions.

In addition, channel components provide functions that are specific to the channel type. The sequence grabber component supplied by Apple uses two types of channel components: video channel components and sound channel components. See Configuration Functions for Video Channel Components for information about the configuration functions that work only with video channels. See Configuration Functions for Sound Channel Components for information about the configuration functions that work only with sound channels.

The SGSetChannelUsage function specifies how your channel is to be used. The sequence grabber component can restrict a channel to use during record or preview operations. In addition, this function allows the sequence grabber component to specify whether your channel plays during a record operation. The SGGetChannelUsage function allows the sequence grabber component to determine a channel’s usage.
The SGGetChannelInfo function allows the sequence grabber component to determine some of the characteristics of your channel. For example, this function returns information indicating whether your channel has a visual or an audio representation.
The SGSetChannelPlayFlags function lets the sequence grabber component influence the speed and quality with which your channel plays captured data. The SGGetChannelPlayFlags function allows the sequence grabber component to determine these flag settings.
The SGSetChannelMaxFrames function establishes a limit on the number of frames that your channel component will capture from a channel.
The SGGetChannelMaxFrames function enables the sequence grabber component to determine that limit.
The SGSetChannelRefCon function allows the sequence grabber component to set the value of a reference constant that your component passes to its callback functions. See Using Callback Functions for Video Channel Components for information about the callback functions that are supported by video channels.
The SGGetDataRate function allows the sequence grabber component to determine how many bytes of captured data your channel is collecting each second.
The SGGetChannelSampleDescription function allows the sequence grabber to retrieve your channel’s sample description. The SGGetChannelTimeScale function allows it to obtain your channel’s time scale.
The sequence grabber can modify or retrieve your channel’s clipping region by calling the SGSetChannelClip or SGGetChannelClip function, respectively. The sequence grabber can work with your channel’s transformation matrix by calling the SGSetChannelMatrix and SGGetChannelMatrix functions.

Configuration Functions for Video Channel Components

Video channel components provide a number of functions that allow the sequence grabber to configure the channel’s video characteristics. This section describes these video channel configuration functions, which the sequence grabber component uses only with video channels:

The SGSetChannelBounds function allows the sequence grabber to set the display boundary rectangle for a video channel. The SGGetChannelBounds function determines a channel’s boundary rectangle.
The sequence grabber component uses the SGGetSrcVideoBounds function to determine the coordinates of the source video boundary rectangle. This rectangle defines the size of the source video image being captured by a video channel. The SGSetVideoRect function specifies a part of the source video boundary rectangle to be captured by the channel. The SGGetVideoRect function retrieves this active source video rectangle.
Typically, video channel components use the Image Compression Manager to compress the video data they capture. The sequence grabber component can control many aspects of this image-compression process. The SGSetVideoCompressorType function specifies the type of image compressor to use. The sequence grabber can determine the type of image compressor currently in use by calling the SGGetVideoCompressorType function. The sequence grabber component can specify a particular image compressor and set many image-compression parameters by calling the SGSetVideoCompressor function. The sequence grabber component can determine which image compressor is being used and its parameter settings by calling the SGGetVideoCompressor function.
Video channel components typically work with a video digitizer component (see About Video Digitizer Components for a discussion of video digitizer components). Sequence grabber components provide functions that allow an application to work with a channel’s video digitizer component. Video channel components, in turn, must provide support for these functions. The sequence grabber component uses the SGGetVideoDigitizerComponent function to determine which video digitizer component is supplying data to your video channel component. The sequence grabber component sets a channel’s video digitizer component by calling the SGSetVideoDigitizerComponent function. If an application changes any video digitizer settings by calling the video digitizer component directly, the sequence grabber component informs your video channel component by calling the SGVideoDigitizerChanged function.
Some video source data may contain unacceptable levels of visual noise or artifacts. One technique for removing this noise is to capture the image and then reduce it in size. During the size reduction process, the noise can be filtered out. Some video channel components may provide functions that allow the sequence grabber component to filter the input video data. The SGSetCompressBuffer function sets a filter buffer for a video channel. The SGGetCompressBuffer function returns information about your filter buffer.
The sequence grabber can work with a video channel’s frame rate by calling the SGSetFrameRate and SGGetFrameRate functions. The sequence grabber can control whether your channel uses an offscreen buffer by calling your SGSetUseScreenBuffer and SGGetUseScreenBuffer functions.
Your SGAlignChannelRect function allows the sequence grabber to determine a channel’s optimum screen position.

Configuration Functions for Sound Channel Components

Sound channel components provide a number of functions that allow sequence grabber components to configure the component’s sound channel. This section describes these sound channel configuration functions. The sequence grabber component uses these functions only with sound channels.

The SGSetChannelVolume function allows the sequence grabber component to control a channel’s sound volume. The sequence grabber component uses the SGGetChannelVolume function to determine a channel’s volume.
The SGSetSoundInputDriver specifies a channel’s sound input device. The sequence grabber component can determine a channel’s sound input device by calling the SGGetSoundInputDriver function. If an application changes any attributes of the sound input device, the sequence grabber component notifies your sound component by calling the SGSoundInputDriverChanged function.
The sequence grabber component can control the amount of sound data your channel works with at one time by calling the SGSetSoundRecordChunkSize function. The sequence grabber component can determine this value by calling the SGGetSoundRecordChunkSize function.
The sequence grabber component controls the rate at which your sound channel samples the input data by calling the SGSetSoundInputRate function. The sequence grabber component can determine the sample rate by calling the SGGetSoundInputRate function.
The sequence grabber can control other sound input parameters by using your SGSetSoundInputParameters and SGGetSoundInputParameters functions.

Controlling Sequence Grabber Channel Components

Sequence grabber channel components must provide a full set of functions that allow the sequence grabber component to control the preview or record operation. The sequence grabber component can use these functions to start and stop the operation, to pause data collection, and to write captured data to a movie. This section describes these functions.

The sequence grabber component uses the SGStartPreview function to start a preview operation. The SGStartRecord function starts a record operation. The SGStop function stops your channel component after a preview or record operation.
The sequence grabber component grants processing time to your channel component by calling the SGIdle function. The sequence grabber notifies you of update events by calling your SGUpdate function.
The sequence grabber pauses the current operation by calling the SGPause function.
The sequence grabber component calls your SGWriteSamples function to write captured data to a movie file after a record operation.
The sequence grabber component prepares your channel component for an upcoming preview or record operation by calling the SGPrepare function. This function also allows the sequence grabber component to verify that your component can support the parameters an application has specified. The SGRelease function releases system resources allocated during the SGPrepare function.

Recording

During a record operation, a sequence grabber component collects the data it captures and formats that data into a QuickTime movie. During a record operation, the sequence grabber component can also play the captured data for the user.

The following are the steps the sequence grabber component follows to record captured data.

As with a preview operation, the sequence grabber component establishes a connection to your channel component by calling the Component Manager’s OpenComponent function. It then initializes your component by calling your SGInitChannel function.
The sequence grabber component then configures your component for the record operation. The SGSetGWorld function sets the graphics world in which the data is to be displayed. The SGSetChannelUsage function specifies each channel that is to be used for recording. At this time, the sequence grabber component can also specify whether your component is to play its data while recording. The application can then use the appropriate channel configuration functions to prepare your channel for the record operation. For video channels, it uses the functions discussed in Configuration Functions for Video Channel Components. For sound channels, the sequence grabber uses the functions discussed in Configuration Functions for Sound Channel Components.
The sequence grabber component starts the record operation by calling your SGStartRecord function. The sequence grabber component then begins collecting data from the channels it has assigned, stores the data in a QuickTime movie, and, optionally, plays that data appropriately. The sequence grabber can pause and restart the record process by calling the SGPause function. During the record operation, the sequence grabber component calls your SGIdle function frequently, so that your channel can perform its operation. The sequence grabber component uses the SGStop function to stop the record operation. At this time, your component saves the movie in the appropriate movie file if the sequence grabber component instructs your component to do so by calling your SGWriteSamples function.
When the application is done recording, it either returns to previewing or closes its connection to your component.

Working With Callback Functions

Sequence grabber components provide callback functions that allow application developers to customize some aspects of capturing video data. It is your channel component’s responsibility to call these callback functions at specified points in the data capture process. The application’s function can then perform any special processing that is appropriate for the application. For example, an application can overlay text, such as a frame number, on each frame of video data as it is captured.

Using Callback Functions for Video Channel Components

Sequence grabber components allow application developers to define a number of callback functions in their applications. Your channel component calls these functions at specific points in the process of collecting, compressing, and displaying the source visual data. By defining callback functions, a developer can control the process more precisely or customize the operation of the sequence grabber component and its channel components.

For example, you could use a callback function to draw a frame number on each video frame as it is collected. In this case, you could use either a compress callback function or a grab-complete callback function. You call the compress function after each frame is collected, in order to compress the frame. You call the grab-complete function just before the compress function or as soon as the frame has been captured.

Note that your channel component need not call each and every callback function. If some functions are inappropriate to the operation of your channel, do not call them. However, if your component calls one function of a pair, be sure to call the other. For example, if your component calls an application’s grab function, you must also call its grab-complete function.

The sequence grabber component uses the SGSetVideoBottlenecks function to assign callback functions to your video channel. The SGGetVideoBottlenecks function allows the sequence grabber to determine the callback functions that have been assigned to your video channel. See the chapter Sequence Grabber Component Functions in this document for details on SGSetVideoBottlenecks and SGGetVideoBottlenecks.

The following application-defined functions are supported by video channels and are described in Application-Defined Functions.

MyAddFrameFunction
MyGrabCompressCompleteFunction
MyCompressCompleteFunction
MyGrabFunction
MyCompressFunction
MyTransferFrameFunction
MyDisplayFunction
MyGrabCompleteFunction

Using Utility Functions for Video Channel Component Callback Functions

Sequence grabber components provide a number of functions that application-defined functions can use. Several channel functions support those sequence grabber component functions.

The sequence grabber component uses the SGGetBufferInfo function to obtain information about a buffer that contains data to be manipulated by a callback function. Application callback functions can use the SGGetBufferInfo function to obtain information about a buffer that you have passed. This information is valid only during record operations, or after your channel has been prepared to record. The SGGetBufferInfo function is described in the chapter Sequence Grabber Component Functions.

The following functions provide default behavior for application-defined grab, grab-complete, display, compress, compress-complete, add-frame, transfer-frame, display-compress, and grab-compress-complete functions:

Your video channel component’s SGGrabFrame function provides the default behavior for an application’s grab function. Applications should call this function only from their grab function.
Your channel component’s SGGrabFrameComplete function provides the default behavior for an application’s grab-complete function. Applications should call this function only from their grab-complete functions.
Your channel component’s SGDisplayFrame function provides the default behavior for an application’s display function. Applications should call this function only from their display functions.
Your video channel component’s SGCompressFrame function provides the default behavior for an application’s compress function. Applications should call this function only from their compress functions.
Your channel component’s SGCompressFrameComplete function provides the default behavior for an application’s compress-complete function. Applications should call this function only from their compress-complete functions.
Your component’s SGAddFrame function provides the default behavior for an application’s add-frame function. Applications should call this function only from their add-frame functions.
Your component’s SGTransferFrameForCompress function provides the default behavior for an application’s transfer-frame function. Applications should call this function only from their transfer-frame functions.
Your component’s SGGrabCompressComplete function provides the default behavior for an application’s grab-compress-complete function. Applications should call this function only from their grab-compress-complete function.
Your component’s SGDisplayCompress function provides the default behavior for an application’s display-compress function. Applications should call this function only from their display-compress function.

Working With Channel Devices

Sequence grabbers provide a number of functions that allow applications to determine the devices that can be, or the device that is, attached to a given sequence grabber channel. These devices, in turn, allow the channel component to control the digitizing equipment. For example, video channels use video digitizer components, and sound channels use sound input drivers. Applications can use these functions to present a list of available devices to the user, allowing the user to select a specific device for each channel. The sequence grabber passes these functions on to your channel component.

The sequence grabber may use the SGGetChannelDeviceList function to retrieve a list of devices that may be used by your channel.

The sequence grabber can use the SGSetChannelDevice function to assign a device to your channel.

The SGGetChannelDeviceList function uses a device list structure to pass information about one or more channel devices. The SGDeviceListRecord data type defines the format of the device list structure.

typedef struct SGDeviceListRecord {

    short               count;                  /* count of devices */

    short               selectedIndex;          /* current device */

    long                reserved;               /* set to 0 */

    SGDeviceName        entry[1];               /* device names */

} SGDeviceListRecord, *SGDeviceListPtr, **SGDeviceList;

Field	Description
`count`	Indicates the number of devices described by this structure. The value of this field corresponds to the number of entries in the device name array defined by the `entry` field.
`selectedIndex`	Identifies the currently active device. The value of this field corresponds to the appropriate entry in the device name array defined by the `entry` field. Note that this value is 0-relative; that is, the first entry has an index number of 0, the second's value is 1, and so on.
`reserved`	Reserved for Apple. Always set to 0.
`entry`	Contains an array of device name structures. Each structure corresponds to one valid device. The `count` field indicates the number of entries in this array. The `SGDeviceName` data type defines the format of a device name structure; this data type is discussed next.

Device list structures contain an array of device name structures. Each device name structure identifies a single device that may be used by the channel. The SGDeviceName data type defines the format of a device name structure.

typedef struct SGDeviceName {

    Str63           name;                   /* device name */

    Handle          icon;                   /* device icon */

    long            flags;                  /* flags */

    long            refCon;                 /* set to 0 */

    long            reserved;               /* set to 0 */

} SGDeviceName;

Parameter	Description
`name`	Contains the name of the device. For video digitizer components, this field contains the component's name as specified in the component resource. For sound input drivers, this field contains the driver name.
`icon`	Contains a handle to the device's icon. Some devices may support an icon, which applications may choose to present to the user. If the device does not support an icon, or if the sequence grabber chooses not to retrieve this information (by setting the `sgDeviceListWithIcons` flag to 0 when it calls the `SGGetChannelDeviceList` function), set this field to `nil.`
`flags`	Reflects the current status of the device. The `sgDeviceNameFlagDeviceUnavailable` flag is defined. When set to 1, this flag indicates that this device is not currently available.
`refCon`	Reserved for Apple. Always set to 0.
`reserved`	Reserved for Apple. Always set to 0.

Utility Functions for Sequence Grabber Channel Components

This section describes several utility functions that sequence grabber components provide to sequence grabber channel components.

The SGAddMovieData function lets you add data and sample references to a movie.
Alternatively, you can use the SGWriteMovieData function to add data to a movie, and the SGAddFrameReference and SGGetNextFrameReference functions to keep track of sample references prior to creating a QuickTime movie from recorded data.
The SGSortDeviceList function allows you to sort the entries in the device list that you create for the sequence grabber when it calls your SGGetChannelDeviceList function.
The SGChangedSource function allows you to tell the sequence grabber that you have changed your source device.
The SGAddFrameReference and SGGetNextFrameReference functions take a pointer to a frame information structure as a parameter. The SeqGrabFrameInfo data type defines the format of a frame information structure.

struct SeqGrabFrameInfo {

    long            frameOffset;        /* offset to the sample */

    long            frameTime;          /* time that frame was captured */

    long            frameSize;          /* number of bytes in sample */

    SGChannel       frameChannel;       /* current connection to channel */

    long            frameRefCon;        /* reference constant for channel */

};

Field	Description
`frameOffset`	Specifies the offset to the sample. Your channel component obtains this value from the `SGWriteMovieData` function.
`frameTime`	Specifies the time at which your channel component captured the frame. This time value is relative to the data sequence. That is, this time is not represented in the context of any fixed time scale. Rather, your channel component must choose and use a time scale consistently for all sample references.
`frameSize`	Specifies the number of bytes in the sample described by the sample reference.
`frameChannel`	Identifies the current connection to your channel.
`frameRefCon`	Contains a reference constant for use by your channel component. You can use this value in any way that is appropriate for your channel component. For example, video channel components may use this value to store a reference to frame differencing information for a temporally compressed image sequence.

Next Previous