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 yourSGInitChannel
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. TheSGSetChannelUsage
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 theSGPause
function. The sequence grabber component uses theSGStop
function to stop the preview. During the preview operation, the sequence grabber component calls yourSGIdle
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. TheSGGetChannelUsage
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. TheSGGetChannelPlayFlags
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. TheSGGetChannelTimeScale
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
orSGGetChannelClip
function, respectively. The sequence grabber can work with your channel’s transformation matrix by calling theSGSetChannelMatrix
andSGGetChannelMatrix
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. TheSGGetChannelBounds
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. TheSGSetVideoRect
function specifies a part of the source video boundary rectangle to be captured by the channel. TheSGGetVideoRect
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 theSGGetVideoCompressorType
function. The sequence grabber component can specify a particular image compressor and set many image-compression parameters by calling theSGSetVideoCompressor
function. The sequence grabber component can determine which image compressor is being used and its parameter settings by calling theSGGetVideoCompressor
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 theSGSetVideoDigitizerComponent
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 theSGVideoDigitizerChanged
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. TheSGGetCompressBuffer
function returns information about your filter buffer.The sequence grabber can work with a video channel’s frame rate by calling the
SGSetFrameRate
andSGGetFrameRate
functions. The sequence grabber can control whether your channel uses an offscreen buffer by calling yourSGSetUseScreenBuffer
andSGGetUseScreenBuffer
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 theSGGetChannelVolume
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 theSGGetSoundInputDriver
function. If an application changes any attributes of the sound input device, the sequence grabber component notifies your sound component by calling theSGSoundInputDriverChanged
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 theSGGetSoundRecordChunkSize
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 theSGGetSoundInputRate
function.The sequence grabber can control other sound input parameters by using your
SGSetSoundInputParameters
andSGGetSoundInputParameters
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. TheSGStartRecord
function starts a record operation. TheSGStop
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 yourSGUpdate
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. TheSGRelease
function releases system resources allocated during theSGPrepare
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 yourSGInitChannel
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. TheSGSetChannelUsage
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 theSGPause
function. During the record operation, the sequence grabber component calls yourSGIdle
function frequently, so that your channel can perform its operation. The sequence grabber component uses theSGStop
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 yourSGWriteSamples
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 |
---|---|
|
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 |
|
Identifies the currently active device. The value of this field corresponds to the appropriate entry in the device name array defined by the |
|
Reserved for Apple. Always set to 0. |
|
Contains an array of device name structures. Each structure corresponds to one valid device. The |
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 |
---|---|
|
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. |
|
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 |
|
Reflects the current status of the device. The |
|
Reserved for Apple. Always set to 0. |
|
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 theSGAddFrameReference
andSGGetNextFrameReference
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 yourSGGetChannelDeviceList
function.The
SGChangedSource
function allows you to tell the sequence grabber that you have changed your source device.The
SGAddFrameReference
andSGGetNextFrameReference
functions take a pointer to a frame information structure as a parameter. TheSeqGrabFrameInfo
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 |
---|---|
|
Specifies the offset to the sample. Your channel component obtains this value from the |
|
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. |
|
Specifies the number of bytes in the sample described by the sample reference. |
|
Identifies the current connection to your channel. |
|
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. |
Copyright © 2005, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01