ADC Home > Reference Library > Reference > QuickTime > Movie Creation > Sequence Grabber Reference for QuickTime >

Next Page > Hide TOC

Sequence Grabber Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
QuickTimeComponents.h

Overview

Sequence Grabber components allow applications to obtain digitized data from external sources, such as video capture boards. The digitized data can be previewed, saved as a QuickTime movie, or both. Sequence grabber components allow applications to capture audio and video easily, without concern for the details of how the data is acquired.

Functions by Task

Configuration Functions for All Channel Components

Configuration Functions for Video Channel Components

Configuring Sequence Grabber Channel Components

Configuring Sequence Grabber Components

Controlling Sequence Grabber Channel Components

Controlling Sequence Grabber Components

Managing Your Panel Component

Managing Your Panel's Settings

Processing Your Panel's Events

Text Channel Support

Utility Functions for Sequence Grabber Channel Components

Video Channel Callback Functions

Working With Channel Characteristics

Working With Channel Devices

Working With Sequence Grabber Characteristics

Working With Sequence Grabber Outputs

Working With Sequence Grabber Settings

Working With Sound Channels

Working With Video Channels

Supporting Functions

Functions

DisposeSGAddFrameBottleUPP

Disposes of an SGAddFrameBottleUPP pointer.

void DisposeSGAddFrameBottleUPP (
   SGAddFrameBottleUPP userUPP
);

Parameters
userUPP

An SGAddFrameBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGCompressBottleUPP

Disposes of an SGCompressBottleUPP pointer.

void DisposeSGCompressBottleUPP (
   SGCompressBottleUPP userUPP
);

Parameters
userUPP

An SGCompressBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGCompressCompleteBottleUPP

Disposes of an SGCompressCompleteBottleUPP pointer.

void DisposeSGCompressCompleteBottleUPP (
   SGCompressCompleteBottleUPP userUPP
);

Parameters
userUPP

An SGCompressCompleteBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGDataUPP

Disposes of an SGDataUPP pointer.

void DisposeSGDataUPP (
   SGDataUPP userUPP
);

Parameters
userUPP

An SGDataUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

DisposeSGDisplayBottleUPP

Disposes of an SGDisplayBottleUPP pointer.

void DisposeSGDisplayBottleUPP (
   SGDisplayBottleUPP userUPP
);

Parameters
userUPP

An SGDisplayBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGDisplayCompressBottleUPP

Disposes of an SGDisplayCompressBottleUPP pointer.

void DisposeSGDisplayCompressBottleUPP (
   SGDisplayCompressBottleUPP userUPP
);

Parameters
userUPP

An SGDisplayCompressBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGGrabBottleUPP

Disposes of an SGGrabBottleUPP pointer.

void DisposeSGGrabBottleUPP (
   SGGrabBottleUPP userUPP
);

Parameters
userUPP

An SGGrabBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGGrabCompleteBottleUPP

Disposes of an SGGrabCompleteBottleUPP pointer.

void DisposeSGGrabCompleteBottleUPP (
   SGGrabCompleteBottleUPP userUPP
);

Parameters
userUPP

An SGGrabCompleteBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGGrabCompressCompleteBottleUPP

Disposes of an SGGrabCompressCompleteBottleUPP pointer.

void DisposeSGGrabCompressCompleteBottleUPP (
   SGGrabCompressCompleteBottleUPP userUPP
);

Parameters
userUPP

An SGGrabCompressCompleteBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSGModalFilterUPP

Disposes of an SGModalFilterUPP pointer.

void DisposeSGModalFilterUPP (
   SGModalFilterUPP userUPP
);

Parameters
userUPP

An SGModalFilterUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

DisposeSGTransferFrameBottleUPP

Disposes of an SGTransferFrameBottleUPP pointer.

void DisposeSGTransferFrameBottleUPP (
   SGTransferFrameBottleUPP userUPP
);

Parameters
userUPP

An SGTransferFrameBottleUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

NewSGAddFrameBottleUPP

Allocates a Universal Procedure Pointer for the SGAddFrameBottleProc callback.

SGAddFrameBottleUPP NewSGAddFrameBottleUPP (
   SGAddFrameBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGAddFrameBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGCompressBottleUPP

Allocates a Universal Procedure Pointer for the SGCompressBottleProc callback.

SGCompressBottleUPP NewSGCompressBottleUPP (
   SGCompressBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGCompressBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGCompressCompleteBottleUPP

Allocates a Universal Procedure Pointer for the SGCompressCompleteBottleProc callback.

SGCompressCompleteBottleUPP NewSGCompressCompleteBottleUPP (
   SGCompressCompleteBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGCompressCompleteBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGDataUPP

Allocates a Universal Procedure Pointer for the SGDataProc callback.

SGDataUPP NewSGDataUPP (
   SGDataProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGDataProc.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

NewSGDisplayBottleUPP

Allocates a Universal Procedure Pointer for the SGDisplayBottleProc callback.

SGDisplayBottleUPP NewSGDisplayBottleUPP (
   SGDisplayBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGDisplayBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGDisplayCompressBottleUPP

Allocates a Universal Procedure Pointer for the SGDisplayCompressBottleProc callback.

SGDisplayCompressBottleUPP NewSGDisplayCompressBottleUPP (
   SGDisplayCompressBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGDisplayCompressBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGGrabBottleUPP

Allocates a Universal Procedure Pointer for the SGGrabBottleProc callback.

SGGrabBottleUPP NewSGGrabBottleUPP (
   SGGrabBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGGrabBottleProc.

Availability
Declared In
QuickTimeComponents.h

NewSGGrabCompleteBottleUPP

Allocates a Universal Procedure Pointer for the SGGrabCompleteBottleProc callback.

SGGrabCompleteBottleUPP NewSGGrabCompleteBottleUPP (
   SGGrabCompleteBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGGrabCompleteBottleProc.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

NewSGGrabCompressCompleteBottleUPP

Allocates a Universal Procedure Pointer for the SGGrabCompressCompleteBottleProc callback.

SGGrabCompressCompleteBottleUPP NewSGGrabCompressCompleteBottleUPP (
   SGGrabCompressCompleteBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGGrabCompressCompleteBottleProc.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

NewSGModalFilterUPP

Allocates a Universal Procedure Pointer for the SGModalFilterProc callback.

SGModalFilterUPP NewSGModalFilterUPP (
   SGModalFilterProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGModalFilterProc.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

NewSGTransferFrameBottleUPP

Allocates a Universal Procedure Pointer for the SGTransferFrameBottleProc callback.

SGTransferFrameBottleUPP NewSGTransferFrameBottleUPP (
   SGTransferFrameBottleProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewSGTransferFrameBottleProc.

Availability
Declared In
QuickTimeComponents.h

SGAddExtendedFrameReference

Stores extended sample references for a channel component.

ComponentResult SGAddExtendedFrameReference (
   SeqGrabComponent s,
   SeqGrabExtendedFrameInfoPtr frameInfo
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

frameInfo

A pointer to a SeqGrabExtendedFrameInfo structure. Your component must place the appropriate information into this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function differs from SGAddFrameReference in that it uses a SeqGrabExtendedFrameInfo structure instead of a SeqGrabFrameInfo structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAddExtendedMovieData

Adds data to a movie without writing data to a movie file.

ComponentResult SGAddExtendedMovieData (
   SeqGrabComponent s,
   SGChannel c,
   Ptr p,
   long len,
   wide *offset,
   long chRefCon,
   TimeValue time,
   short writeType,
   SGOutput *whichOutput
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

c

Identifies the connection to your channel.

p

The location of the data to be added to the movie.

len

The number of bytes of data to be added to the movie.

offset

A pointer to a wide integer that receives the offset to the new data in the movie. If the movie is in memory, the returned offset reflects the location the data will have in the movie on a permanent storage device.

chRefCon

The reference constant for your channel.

time

The time at which the frame was captured, expressed in the time scale associated with your channel.

writeType

A constant (see below) that determines the type of write operation to be used. See these constants:

  • seqGrabWriteAppend

  • seqGrabWriteReserve

  • seqGrabWriteFill

whichOutput

The use of whichOutput depends on the value passed in the writeType parameter. If writeType is seqGrabWriteAppend or seqGrabWriteReserve, the whichOutput parameter is a return value specifying the sequence grabber output to which data was written or in which space was reserved. If writeType is seqGrabWriteFill, the whichOutput parameter is an input value indicating which sequence grabber output the data should be written to.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function differs from SGAddMovieData in two respects: the offset parameter allows a 64-bit value, and the whichOutput parameter does not exist in SGAddMovieData.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAddFrame

Provides default values for your add-frame function.

ComponentResult SGAddFrame (
   SGChannel c,
   short bufferNum,
   TimeValue atTime,
   TimeScale scale,
   const SGCompressInfo *ci
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber component provides this value to your add-frame function.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your add-frame function.

atTime

The time at which the frame was captured, in the time scale specified by the scale parameter. The sequence grabber component provides this value to your add-frame function. Your add-frame function can change this value before calling this function. You can determine the duration of a frame by subtracting its capture time from the capture time of the next frame in the sequence.

scale

The time scale of the movie. The sequence grabber component provides this value to your add-frame function.

ci

A pointer to a SGCompressInfo structure. This structure contains information describing the compression characteristics of the image to be added to the movie.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You should call this function only from your add-frame function. If you call it at any other time, results are unpredictable.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAddFrameReference

Stores sample references for a channel component.

ComponentResult SGAddFrameReference (
   SeqGrabComponent s,
   SeqGrabFrameInfoPtr frameInfo
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

frameInfo

A pointer to a SeqGrabFrameInfo structure. Your component must completely specify the reference by placing the appropriate information into the record referred to by this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAddMovieData

Lets a channel component add data to a movie.

ComponentResult SGAddMovieData (
   SeqGrabComponent s,
   SGChannel c,
   Ptr p,
   long len,
   long *offset,
   long chRefCon,
   TimeValue time,
   short writeType
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

c

Identifies the connection to your channel.

p

The location of the data to be added to the movie.

len

Indicates the number of bytes of data to be added to the movie.

offset

A pointer to a field that is to receive the offset to the new data in the movie. The sequence grabber component returns an offset that is correct in the context of the movie resource, even if the movie is currently stored in memory. That is, if the movie is in memory, the returned offset reflects the location that the data will have in a movie on a permanent storage device, such as a disk.

chRefCon

Your channel's reference constant.

time

The time at which your channel captured the frame. This time value is expressed in your channel's time scale.

writeType

A constant (see below) that determines the type of write operation to be used. See these constants:

  • seqGrabWriteAppend

  • seqGrabWriteReserve

  • seqGrabWriteFill

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function combines the services provided by SGWriteMovieData and SGAddFrameReference. Your channel component should not write data directly to the movie file; use this function instead.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGAddOutputDataRefToMedia

Manages capture sessions that involve multiple data references.

ComponentResult SGAddOutputDataRefToMedia (
   SeqGrabComponent s,
   SGOutput sgOut,
   Media theMedia,
   SampleDescriptionHandle desc
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

sgOut

A pointer to the current sequence grabber output.

theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

desc

A handle to a SampleDescription structure that contains an index, which is assigned to the data by this function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is usually called from the SGWriteSamples function of a sequence grabber channel component. You pass to it a sequence grabber output along with a media and SampleDescription structure, and it adds the data reference to the data reference list of the specified media. It also updates the data reference index field of the SampleDescription structure to refer to the data reference.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAlignChannelRect

Determines whether or not a channel prefers to draw at a particular screen location.

ComponentResult SGAlignChannelRect (
   SGChannel c,
   Rect *r
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

r

A pointer to a Rect structure. On entry, this structure contains coordinates at which the sequence grabber would like to draw your captured video image. If your component can draw more efficiently or at a higher frame rate at a different location, update the contents of this structure to reflect where you would prefer to draw. The rectangle will be passed in with global, not local, coordinates.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is called by a sequence grabber to determine whether or not a channel prefers to draw at a particular screen location.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGAppendDeviceListToMenu

Places a list of device names into a specified menu.

ComponentResult SGAppendDeviceListToMenu (
   SeqGrabComponent s,
   SGDeviceList list,
   MenuRef mh
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

list

A pointer to a pointer to an SGDeviceListRecord. The sequence grabber appends the name of each device in the list to the menu specified by the mh parameter. If the sgDeviceNameFlagDeviceUnavailable flag is set to 1 for a device in the list, the sequence grabber disables the menu item corresponding to that device.

mh

A handle to the menu to which the device names are to be appended.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChangedSource

Informs the sequence grabber that a component is now using a different device.

ComponentResult SGChangedSource (
   SeqGrabComponent s,
   SGChannel c
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

c

Identifies the connection to your channel.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChannelGetCodecSettings

Gets the codec settings for a sequence grabber channel.

ComponentResult SGChannelGetCodecSettings (
   SGChannel c,
   Handle *settings
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

settings

A pointer to a handle that the codec should resize and fill in with the current internal settings. These settings are codec-defined and usually opaque. Don't dispose of this handle.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
QuickTimeComponents.h

SGChannelGetDataSourceName

Returns the data source name for a track.

ComponentResult SGChannelGetDataSourceName (
   SGChannel c,
   Str255 name,
   ScriptCode *scriptTag
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

name

A string that is to receive the source identification information. Set this parameter to NIL if you do not want to retrieve the name.

scriptTag

A field that is to receive the source information's language code; see Localization Codes. Set this parameter to NIL if you do not want this information.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to get the source information specified with SGChannelSetDataSourceName.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChannelGetRequestedDataRate

Returns the current maximum data rate requested for a channel.

ComponentResult SGChannelGetRequestedDataRate (
   SGChannel c,
   long *bytesPerSecond
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bytesPerSecond

Points to a field that is to receive the maximum data rate requested by the sequence grabber component. This field is set to 0 if the sequence grabber has not set any restrictions.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows the sequence grabber component to retrieve the current maximum data rate value from your channel component.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChannelPutPicture

Undocumented

ComponentResult SGChannelPutPicture (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChannelSetCodecSettings

Sets the codec settings for a sequence grabber channel.

ComponentResult SGChannelSetCodecSettings (
   SGChannel c,
   Handle settings
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

settings

Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
QuickTimeComponents.h

SGChannelSetDataSourceName

Sets the data source name for a track.

ComponentResult SGChannelSetDataSourceName (
   SGChannel c,
   ConstStr255Param name,
   ScriptCode scriptTag
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

name

A string that contains the source identification information. The source information identifies the source of the video data (for example, a videotape name).

scriptTag

The language of the source identification information; see Localization Codes.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to set the source information for a sequence grabber channel. You must set this information before you start digitizing. The sequence grabber channel stores this information in a timecode track in the movie created after the capture is complete. If the video digitizer does not provide timecode information, the sequence grabber does not save this information.

Special Considerations

This function is currently supported only by video channels.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGChannelSetRequestedDataRate

Specifies the maximum requested data rate for a channel.

ComponentResult SGChannelSetRequestedDataRate (
   SGChannel c,
   long bytesPerSecond
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bytesPerSecond

The maximum data rate requested by the sequence grabber component, in bytes per second. The sequence grabber component sets this parameter to 0 to remove any data-rate restrictions.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows the sequence grabber component to specify the maximum rate at which it would like to receive data from your channel component. The data rate supplied by the sequence grabber component represents a requested data rate; your component may not be able to observe that rate under all conditions.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGCompressFrame

Provides the default behavior for your compress function.

ComponentResult SGCompressFrame (
   SGChannel c,
   short bufferNum
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber provides this value to your compress function.

bufferNum

The buffer. The sequence grabber provides this value to your compress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Special Considerations

You should call this function only from your compress function. If you call it at any other time, results are unpredictable.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGCompressFrameComplete

Provides the default behavior for your compress-complete function.

ComponentResult SGCompressFrameComplete (
   SGChannel c,
   short bufferNum,
   Boolean *done,
   SGCompressInfo *ci
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber component provides this value to your compress-complete function.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your compress-complete function.

done

A pointer to a Boolean value. The function sets this Boolean value to TRUE if the compression is complete, or FALSE if the operation is incomplete. The sequence grabber component provides this pointer to your compress-complete function.

ci

A pointer to a SGCompressInfo structure. If the compression is complete, the function completely formats this structure with information that is appropriate to the frame just compressed. The sequence grabber component provides this pointer to your compress-complete function.

Return Value

See Error Codes. Returns noErr if there is no error.

Special Considerations

You should call this function only from your compress-complete function. If you call it at any other time, results are unpredictable.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGDisplayCompress

Provides the default behavior for your display-compress function.

ComponentResult SGDisplayCompress (
   SGChannel c,
   Ptr dataPtr,
   ImageDescriptionHandle desc,
   MatrixRecord *mp,
   RgnHandle clipRgn
);

Parameters
c

Identifies the channel for this operation. The sequence grabber provides this value to your display-compress function.

dataPtr

A pointer to the compressed image data. The sequence grabber provides this pointer to your display-compress function.

desc

A handle to the ImageDescription structure to use for the decompression operation. The sequence grabber provides this handle to your display-compress function.

mp

A pointer to a MatrixRecord structure. This structure contains the transformation matrix to use when displaying the image. If there is no matrix for the operation, set this parameter to NIL.

clipRgn

A handle to a MacRegion structure that defines the clipping region for the destination image. This region is defined in the destination coordinate system. If there is no clipping region, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Special Considerations

You should call this function only from your display-compress function. If you call it at any other time, results are unpredictable.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGDisplayFrame

Provides the default behavior for your display function.

ComponentResult SGDisplayFrame (
   SGChannel c,
   short bufferNum,
   const MatrixRecord *mp,
   RgnHandle clipRgn
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber component provides this value to your display function.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your display function.

mp

A pointer to a MatrixRecord structure for the display operation. If there is no matrix for the operation, set this parameter to NIL.

clipRgn

A handle to a MacRegion structure that defines the clipping region for the destination image. This region is defined in the destination coordinate system. If there is no clipping region, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Special Considerations

You should call this function only from your display function. If you call it at any other time, results are unpredictable.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGDisposeChannel

Removes a channel from a sequence grabber component.

ComponentResult SGDisposeChannel (
   SeqGrabComponent s,
   SGChannel c
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

c

The reference that identifies the channel you want to close. You obtain this reference from SGNewChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGDisposeDeviceList

Disposes of a device list.

ComponentResult SGDisposeDeviceList (
   SeqGrabComponent s,
   SGDeviceList list
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

list

A pointer to a pointer to an SGDeviceListRecord structure. The sequence grabber disposes of the memory used by this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGDisposeOutput

Disposes of an existing sequence grabber output.

ComponentResult SGDisposeOutput (
   SeqGrabComponent s,
   SGOutput sgOut
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function to dispose of an existing output. If any sequence grabber channels are using this output, the sequence grabber component assigns them to an undefined output.

Special Considerations

You cannot dispose of an output when the sequence grabber component is in record mode.

Availability
Declared In
QuickTimeComponents.h

SGGetAdditionalSoundRates

Returns the additional sound sample rates added to a specified sequence grabber sound channel.

ComponentResult SGGetAdditionalSoundRates (
   SGChannel c,
   Handle *rates
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

rates

A pointer to the handle where the list of additional sample rates should be returned. If no additional sample rates have been set, this function sets the rates handle to NIL. The caller of this routine is responsible for disposing of the returned handle.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetAlignmentProc

Obtains information about the best screen positions for a sequence grabber's video image in terms of appearance and maximum performance.

ComponentResult SGGetAlignmentProc (
   SeqGrabComponent s,
   ICMAlignmentProcRecordPtr alignmentProc
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

alignmentProc

A pointer to an ICMAlignmentProcRecord structure. The sequence grabber places its alignment information into this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetBufferInfo

Obtains information about a buffer that has been passed to a callback function.

ComponentResult SGGetBufferInfo (
   SGChannel c,
   short bufferNum,
   PixMapHandle *bufferPM,
   Rect *bufferRect,
   GWorldPtr *compressBuffer,
   Rect *compressBufferRect
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your callback function.

bufferPM

A pointer to a location that is to receive a handle to the PixMap structure that contains the image. Note that this structure may be offscreen. Do not dispose of this structure. If you do not want this information, set this parameter to NIL.

bufferRect

A pointer to a Rect structure that is to receive the dimensions of the image's boundary rectangle. If you do not want this information, set this parameter to NIL.

compressBuffer

A pointer to a location that is to receive a pointer to the filter buffer for the image. The sequence grabber component returns this information only if your application has assigned a filter buffer to this video channel. You assign a filter buffer by calling SGSetCompressBuffer. Do not dispose of this buffer.

compressBufferRect

A pointer to a Rect structure that is to receive the dimensions of the filter buffer for the image. The sequence grabber component returns this information only if your application has assigned a filter buffer to this video channel. You assign a filter buffer by calling SGSetCompressBuffer. If you have not assigned a filter buffer, the sequence grabber component returns an empty rectangle. If you do not want this information, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelBounds

Determines a channel's display boundary rectangle.

ComponentResult SGGetChannelBounds (
   SGChannel c,
   Rect *bounds
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bounds

A pointer to a Rect structure that is to receive information about your channel's display boundary rectangle.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelClip

Retrieves a channel's clipping region.

ComponentResult SGGetChannelClip (
   SGChannel c,
   RgnHandle *theClip
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

theClip

A pointer to a handle that is to receive a MacRegion structure that defines the clipping region. The application is responsible for disposing of this handle. If there is no clipping region, set this handle to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Special Considerations

Note that some devices may not support clipping.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelDeviceAndInputNames

Returns the sequence grabber's current device and input names.

ComponentResult SGGetChannelDeviceAndInputNames (
   SGChannel c,
   Str255 outDeviceName,
   Str255 outInputName,
   short *outInputNumber
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

outDeviceName

The current device names for display to the user.

outInputName

The current input names for display to the user.

outInputNumber

A pointer to the number of currently selected inputs.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This is a utility call that lets you find out the sequence grabber's current device and input names, instead of having to call GetDeviceList and walk it yourself. Pass NIL for parameters you are not interested in.

Version Notes

Introduced in QuickTime 6.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelDeviceList

Retrieves a list of the devices that are valid for a specified channel.

ComponentResult SGGetChannelDeviceList (
   SGChannel c,
   long selectionFlags,
   SGDeviceList *list
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

selectionFlags

Flags (see below) that control the data you are to return for each device. See these constants:

  • sgDeviceListWithIcons

  • sgDeviceListDontCheckAvailability

  • sgDeviceListIncludeInputs

list

A pointer to a pointer to an SGDeviceListRecord structure. The channel creates this structure and returns a pointer to it in the field referred to by this parameter. Applications use SGDisposeDeviceList to dispose of the memory used by the list.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function can be useful for retrieving the name of the current device. Retrieve the device list and use the selectedIndex field to determine which device is currently in use.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelInfo

Determines how a channel's data is represented to the user: as visual data or audio data, or both.

ComponentResult SGGetChannelInfo (
   SGChannel c,
   long *channelInfo
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

channelInfo

A pointer to a long integer that is to receive channel information flags (see below). You may set more than one flag to 1. Set unused flags to 0. See these constants:

  • seqGrabHasBounds

  • seqGrabHasVolume

  • seqGrabHasDiscreteSamples

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetChannelMatrix

Retrieves a channel's display transformation matrix.

ComponentResult SGGetChannelMatrix (
   SGChannel c,
   MatrixRecord *m
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

m

A pointer to a MatrixRecord structure. Place your current matrix values into this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelMaxFrames

Determines the number of frames left to be captured from a specified channel.

ComponentResult SGGetChannelMaxFrames (
   SGChannel c,
   long *frameCount
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

frameCount

A pointer to a long integer that is to receive a value specifying the number of frames left to be captured during the preview or record operation. If the returned value is -1, the sequence grabber channel component captures as many frames as it can.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetChannelPlayFlags

Retrieves the playback control flags that you set with SGSetChannelPlayFlags.

ComponentResult SGGetChannelPlayFlags (
   SGChannel c,
   long *playFlags
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

playFlags

A pointer to a long integer that is to receive flags (see below) that influence channel playback. Set unused flags to 0. See these constants:

  • channelPlayNormal

  • channelPlayFast

  • channelPlayHighQuality

  • channelPlayAllData

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelRefCon

Returns a reference constant that was previously set by SGSetChannelRefCon.

ComponentResult SGGetChannelRefCon (
   SGChannel c,
   long *refCon
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

refCon

A pointer to the reference constant set by SGSetChannelRefCon, normally used to point to a data structure containing information your sequence grabber channel needs.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelSampleDescription

Retrieves a channel's sample description structure.

ComponentResult SGGetChannelSampleDescription (
   SGChannel c,
   Handle sampleDesc
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

sampleDesc

A handle that is to receive the structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The channel returns a structure that is appropriate to the type of data being captured. For video channels, the channel component returns an ImageDescription structure; for sound channels, it receives a SoundDescription structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelSettings

Retrieves the current settings of a channel used by the sequence grabber.

ComponentResult SGGetChannelSettings (
   SeqGrabComponent s,
   SGChannel c,
   UserData *ud,
   long flags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

ud

On return, a pointer to a UserDataRecord structure that contains the configuration information.

flags

Reserved for Apple. Set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelTimeBase

Retrieves a reference to the time base that is being used by a sequence grabber channel.

ComponentResult SGGetChannelTimeBase (
   SGChannel c,
   TimeBase *tb
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

tb

A pointer to a time base identifier, such as that returned by NewTimeBase.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelTimeScale

Lets the sequence grabber retrieve a channel's time scale.

ComponentResult SGGetChannelTimeScale (
   SGChannel c,
   TimeScale *scale
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

scale

A pointer to a time scale. Your channel component places information about its time scale into this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The time scale you return typically corresponds to the time scale of the media that has been created by your channel. Applications may use this time scale in their data functions.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelUsage

Determines how the sequence grabber component is using a channel.

ComponentResult SGGetChannelUsage (
   SGChannel c,
   long *usage
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

usage

A pointer to a location that is to receive flags (see below) that specify how your channel is to be used. You may set more than one of these flags to 1. Set unused flags to 0. See these constants:

  • seqGrabRecord

  • seqGrabPreview

  • seqGrabPlayDuringRecord

  • seqGrabLowLatencyCapture

  • seqGrabAlwaysUseTimeBase

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier. Flags added in QuickTime 6.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetChannelVolume

Determines a channel's sound volume setting.

ComponentResult SGGetChannelVolume (
   SGChannel c,
   short *volume
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

volume

A pointer to an integer that is to receive the volume setting of the channel represented as a 16-bit, fixed-point number. The high-order 8 bits contain the integer part of the value; the low-order 8 bits contain the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetCompressBuffer

Returns information about the filter buffer established for a video channel.

ComponentResult SGGetCompressBuffer (
   SGChannel c,
   short *depth,
   Rect *compressSize
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

depth

A pointer to a field that is to receive the pixel depth of the filter buffer. If your component is not filtering the input video data, set the returned value to 0.

compressSize

A pointer to a Rect structure that is to receive the dimensions of the filter buffer. If your component is not filtering the input video data, return an empty rectangle (all coordinates set to 0).

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetDataOutput

Determines the movie file that is currently assigned to a sequence grabber component and the control flags that would govern a record operation.

ComponentResult SGGetDataOutput (
   SeqGrabComponent s,
   FSSpec *movieFile,
   long *whereFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

movieFile

A pointer to an FSSpec structure that is to receive information about the movie file for this record operation.

whereFlags

A pointer to a long integer that is to receive flags (see below) that control the record operation. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You set the characteristics returned by this function by calling SGSetDataOutput. If you have not set these characteristics before calling this function, the returned data is meaningless.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetDataOutputStorageSpaceRemaining

Returns the amount of space remaining in the data reference associated with an output.

ComponentResult SGGetDataOutputStorageSpaceRemaining (
   SeqGrabComponent s,
   SGOutput sgOut,
   unsigned long *space
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

space

A pointer to an unsigned long integer, where the sequence grabber component returns a value that indicates the number of bytes of space remaining in the data reference associated with the output.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function in place of SGGetStorageSpaceRemaining in cases where you are working with more than one output.

Version Notes

A sequence grabber output ties a sequence grabber channel to a specified data reference for the output of captured data. If you are capturing to a single movie file, you can continue to use SGSetDataOutput or SGSetDataRef to specify the sequence grabber's destination. However, if you want to capture movie data into several different files or data references, you must use sequence grabber outputs to do so. Even if you are using outputs, you must still use SGSetDataOutput or SGSetDataRef to identify where the sequence grabber should create the movie resource. You are responsible for creating outputs, assigning them to sequence grabber channels, and disposing of them when you are done.

Availability
Declared In
QuickTimeComponents.h

SGGetDataOutputStorageSpaceRemaining64

Provides a 64-bit version of SGGetDataOutputStorageSpaceRemaining.

ComponentResult SGGetDataOutputStorageSpaceRemaining64 (
   SeqGrabComponent s,
   SGOutput sgOut,
   wide *space
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

space

A pointer to a 64-bit wide integer, where the sequence grabber component returns a value that indicates the number of bytes of space remaining in the data reference associated with the output.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 5.

Availability
Declared In
QuickTimeComponents.h

SGGetDataRate

Determines for a sequence grabber how much recording time is left.

ComponentResult SGGetDataRate (
   SGChannel c,
   long *bytesPerSecond
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bytesPerSecond

A pointer to a long integer that is to receive a value indicating the number of bytes your component is recording per second. Your component calculates this value based on its current operational parameters.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetDataRef

Determines the data reference currently assigned to a sequence grabber component and the control flags that would govern a record operation.

ComponentResult SGGetDataRef (
   SeqGrabComponent s,
   Handle *dataRef,
   OSType *dataRefType,
   long *whereFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

dataRef

A pointer to a handle that is to receive the information that identifies the destination container.

dataRefType

A pointer to a field that is to receive the type of data reference.

whereFlags

A pointer to a long integer that is to receive flags (see below) that control the record operation. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to determine the data reference that is currently assigned to a sequence grabber component and the control flags that would govern a record operation. You set these characteristics by calling SGSetDataRef. If you have not set these characteristics before calling this function, the returned data is meaningless.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetFlags

Retrieves a sequence grabber's control flags.

ComponentResult SGGetFlags (
   SeqGrabComponent s,
   long *sgFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgFlags

A pointer to a long integer that is to receive the control flag (see below) for the current operation. See these constants:

  • sgFlagControlledGrab

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetFrameRate

Retrieves a video channel's frame rate for recording.

ComponentResult SGGetFrameRate (
   SGChannel c,
   Fixed *frameRate
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

frameRate

A pointer to a field to receive the current frame rate.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetGWorld

Determines the graphics port and device for a sequence grabber component.

ComponentResult SGGetGWorld (
   SeqGrabComponent s,
   CGrafPtr *gp,
   GDHandle *gd
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

gp

A pointer to a location that is to receive a pointer to the destination graphics port. Set this parameter to NIL if you are not interested in this information.

gd

A pointer to a location that is to receive a handle to the destination graphics device. Set this parameter to NIL if you are not interested in this information.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetIndChannel

Collects information about all of the channel components currently in use by a sequence grabber component.

ComponentResult SGGetIndChannel (
   SeqGrabComponent s,
   short index,
   SGChannel *ref,
   OSType *chanType
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

index

Specifies an index value that identifies the channel to be queried. The first channel has an index value of 1.

ref

A pointer to a field to receive a value identifying your connection to the channel. If you do not want to receive this information, set this parameter to NIL.

chanType

A pointer to a field to receive the channel's subtype value (see below). This value indicates the media type supported by the channel component. See these constants:

  • VideoMediaType

  • SoundMediaType

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetInstrument

Gets a tone description for a music sequence grabber channel.

ComponentResult SGGetInstrument (
   SGChannel c,
   ToneDescription *td
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

td

Pointer to a ToneDescription structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetLastMovieResID

Retrieves the last resource ID used by the sequence grabber component.

ComponentResult SGGetLastMovieResID (
   SeqGrabComponent s,
   short *resID
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

resID

A pointer to an integer that is to receive the resource ID the sequence grabber assigned to the movie resource it just created.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetMaximumRecordTime

Determines the time limit you have set for a record operation.

ComponentResult SGGetMaximumRecordTime (
   SeqGrabComponent s,
   unsigned long *ticks
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

ticks

A pointer to a long integer that is to receive a value indicating the maximum duration for the record operation, in system ticks (sixtieths of a second). A value of 0 indicates that there is no time limit.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetMode

Determines whether a sequence grabber component is in preview mode or record mode.

ComponentResult SGGetMode (
   SeqGrabComponent s,
   Boolean *previewMode,
   Boolean *recordMode
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

previewMode

A pointer to a Boolean. The sequence grabber component sets this field to TRUE if the component is in preview mode.

recordMode

A pointer to a Boolean. The sequence grabber component sets this field to TRUE if the component is in record mode.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetMovie

Returns a reference to the movie that contains the data collected during a record operation.

Movie SGGetMovie (
   SeqGrabComponent s
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

Return Value

A movie identifier, such as that returned from NewMovie.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetNextExtendedFrameReference

Allows a channel component to retrieve the sample references stored previously by SGAddExtendedMovieData or SGAddExtendedFrameReference.

ComponentResult SGGetNextExtendedFrameReference (
   SeqGrabComponent s,
   SeqGrabExtendedFrameInfoPtr frameInfo,
   TimeValue *frameDuration,
   long *frameNumber
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

frameInfo

A pointer to a SeqGrabExtendedFrameInfo structure. Your component must place the appropriate information into this structure.

frameDuration

A pointer to a time value. The sequence grabber component calculates the duration of the specified frame and returns that duration in this structure. The sequence grabber component cannot calculate the duration of the last frame in a sequence. For the last frame, the time value is set to -1.

frameNumber

A pointer to a long integer representing the frame number. Frame numbers need not be sequential, and need not start at 0. To retrieve information about the first frame in a movie, set the integer to -1.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your channel component can process frame references sequentially or randomly. You can specify any relative frame for which you want to retrieve information.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetNextFrameReference

Lets a channel component retrieve the sample references that were stored by calling SGAddMovieData or SGAddFrameReference.

ComponentResult SGGetNextFrameReference (
   SeqGrabComponent s,
   SeqGrabFrameInfoPtr frameInfo,
   TimeValue *frameDuration,
   long *frameNumber
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

frameInfo

A pointer to a SeqGrabFrameInfo structure. Your component must identify itself to the sequence grabber component by setting the frameChannel field of this structure to the component instance that identifies the current connection to your channel. You get this value from SGNewChannel or SGNewChannelFromComponent. The sequence grabber component then returns information about the specified frame in the remaining fields of this structure.

frameDuration

A pointer to a time value. The sequence grabber component calculates the duration of the specified frame and returns that duration in the structure referred to by this parameter. The sequence grabber component cannot calculate the duration of the last frame in a sequence. In this case, the sequence grabber component sets the returned time value to -1.

frameNumber

A pointer to a long integer. Your channel component specifies the frame number corresponding to the frame about which you want to retrieve information. Frames are numbered starting at 0. However, frame numbers need not start at 0, and they need not be sequential. Set the integer to -1 to retrieve information about the first frame in a movie.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetOutputDataReference

Returns information about the data reference associated with the specified sequence grabber output.

ComponentResult SGGetOutputDataReference (
   SeqGrabComponent s,
   SGOutput sgOut,
   Handle *dataRef,
   OSType *dataRefType
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

dataRef

A pointer to the handle in which the data reference is returned. If you do not need the data reference, set this parameter to NIL.

dataRefType

A pointer in which the type of the data reference is returned. If you do not need this information, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The caller is responsible for disposing of the returned handle.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetOutputMaximumOffset

Returns the maximum offset for data written to the specified sequence grabber output.

ComponentResult SGGetOutputMaximumOffset (
   SeqGrabComponent s,
   SGOutput sgOut,
   wide *maxOffset
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the current sequence grabber output. You obtain this identifier by calling SGNewOutput.

maxOffset

A pointer to the value of the maximum offset for data written to this output. This value is initialized to (2^32-1) on systems with a 32-bit file system, and (2^64-1) on systems with a 64-bit file system.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetOutputNextOutput

Returns the next sequence grabber output for the specified output.

ComponentResult SGGetOutputNextOutput (
   SeqGrabComponent s,
   SGOutput sgOut,
   SGOutput *nextOut
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the current sequence grabber output. You obtain this identifier by calling SGNewOutput.

nextOut

A pointer to the next output to be used. If there is no next output, this value is NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetPause

Determines whether the sequence grabber is paused.

ComponentResult SGGetPause (
   SeqGrabComponent s,
   Byte *paused
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

paused

A pointer to a field that is to receive a constant (see below) that indicates whether the sequence grabber is currently paused. See these constants:

  • seqGrabUnpause

  • seqGrabPause

  • seqGrabPauseForMenu

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetPreferredPacketSize

Returns the preferred packet size for the sequence grabber component.

ComponentResult SGGetPreferredPacketSize (
   SGChannel c,
   long *preferredPacketSizeInBytes
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

preferredPacketSizeInBytes

The preferred packet size in bytes.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

SGGetPreferredPacketSize was added in QuickTime 2.5 to support video conferencing applications.

Availability
Declared In
QuickTimeComponents.h

SGGetSettings

Retrieves the current settings of all channels used by the sequence grabber.

ComponentResult SGGetSettings (
   SeqGrabComponent s,
   UserData *ud,
   long flags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

ud

A pointer to a space where the sequence grabber returns a pointer to a UserDataRecord structure that contains the configuration information. Your application is responsible for disposing of this structure when it is done with it.

flags

Reserved for Apple. Set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetSoundInputDriver

Determines the sound input device currently in use by a sound channel component.

long SGGetSoundInputDriver (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

A reference to the sound input device. If your sound channel is not using a sound input device, returns NIL.

Discussion

You may want to gain access to the sound input device if you want to change the device's configuration.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetSoundInputParameters

Retrieves various parameters that relate to sound recording.

ComponentResult SGGetSoundInputParameters (
   SGChannel c,
   short *sampleSize,
   short *numChannels,
   OSType *compressionType
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

sampleSize

A pointer to a field to receive the sample size. Set this field to 8 for 8-bit sound or to 16 for 16-bit sound.

numChannels

A pointer to a field to receive the number of sound channels used by the sound sample. Set this field to 1 for monaural sounds or to 2 for stereo sounds.

compressionType

A pointer to a field to receive the format of the sound data (see below). See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetSoundInputRate

Determines the rate at which the sound channel is collecting sound data.

Fixed SGGetSoundInputRate (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

A fixed-point number that indicates the number of samples your sound channel collects per second.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetSoundRecordChunkSize

Determines the amount of sound data the sequence grabber component works with at a time.

long SGGetSoundRecordChunkSize (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

A long integer that specifies the number of seconds of sound data your channel works with at a time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetSrcVideoBounds

Determines the size of the source video boundary rectangle.

ComponentResult SGGetSrcVideoBounds (
   SGChannel c,
   Rect *r
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

r

A pointer to a Rect structure that is to receive information about your channel's source video boundary rectangle.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

For video channel components that work with video digitizer components, the source video boundary rectangle corresponds to the video digitizer's active source rectangle.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetStorageSpaceRemaining

Monitors the amount of space remaining for use during a record operation.

ComponentResult SGGetStorageSpaceRemaining (
   SeqGrabComponent s,
   unsigned long *bytes
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

bytes

A pointer to a long integer that is to receive a value indicating the amount of space remaining for the current record operation. If you are recording to memory, this value contains information about the amount of memory remaining. If you are recording to a movie file, this value contains information about the amount of storage space available on the device that holds the file.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You can call this function only after you have started a record operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetStorageSpaceRemaining64

Provides a 64-bit version of SGGetStorageSpaceRemaining.

ComponentResult SGGetStorageSpaceRemaining64 (
   SeqGrabComponent s,
   wide *bytes
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

bytes

A pointer to a wide integer that is to receive a value indicating the amount of space remaining for the current record operation. If you are recording to memory, this value contains information about the amount of memory remaining. If you are recording to a movie file, this value contains information about the amount of storage space available on the device that holds the file.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
QuickTimeComponents.h

SGGetTextReturnToSpaceValue

Indicates whether the text channel component should replace return characters with spaces.

ComponentResult SGGetTextReturnToSpaceValue (
   SGChannel c,
   short *rettospace
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

rettospace

A pointer to a 16-bit integer. On return, this parameter is TRUE if the text channel is replacing return characters with spaces, or FALSE if the text channel is not replacing return characters with spaces.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When you capture text from a closed-caption television source, the text is composed of four lines of text of up to 32 characters each, each line separated by a return character. Sometimes it is useful to replace the return characters with spaces. You can call this function to determine whether the text channel component is replacing return characters with spaces.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetTimeBase

Retrieves a reference to the time base that is being used by a sequence grabber component.

ComponentResult SGGetTimeBase (
   SeqGrabComponent s,
   TimeBase *tb
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

tb

A pointer to a time base identifier, such as that returned by NewTimeBase.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetTimeRemaining

Obtains an estimate of the amount of recording time that remains for the current record operation.

ComponentResult SGGetTimeRemaining (
   SeqGrabComponent s,
   long *ticksLeft
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

ticksLeft

A pointer to a long integer that is to receive a value indicating an estimate of the amount of time remaining for the current record operation. This value is expressed in system ticks (sixtieths of a second).

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetUserVideoCompressorList

Returns the video compression formats to be displayed by the specified sequence grabber video channel.

ComponentResult SGGetUserVideoCompressorList (
   SGChannel c,
   Handle *compressorTypes
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

compressorTypes

A pointer to handle where the list of video compression formats should be returned.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns a copy of the list of video compression formats previously passed to SGSetUserVideoCompressorList. If no video compression formats have been set, it sets the compressorTypes handle to NIL. The caller of this routine is responsible for disposing of the returned handle.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetUseScreenBuffer

Determines whether a video channel is allowed to use an offscreen buffer.

ComponentResult SGGetUseScreenBuffer (
   SGChannel c,
   Boolean *useScreenBuffer
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

useScreenBuffer

A pointer to a Boolean value. The channel component sets this field to TRUE if it draws directly to the screen, or FALSE if it can draw to an offscreen buffer.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function can be called by a sequence grabber client to determine whether or not a video channel can use an offscreen buffer. Some video capture hardware can only capture to the screen.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetVideoBottlenecks

Determines the callback functions that have been assigned to a video channel.

ComponentResult SGGetVideoBottlenecks (
   SGChannel c,
   VideoBottles *vb
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

vb

A pointer to a VideoBottles structure. This function sets the fields of that structure to indicate the callback functions that have been assigned to this video channel. You must set the procCount field in the VideoBottles structure to 9.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetVideoCompressor

Determines a channel's current image compression parameters.

ComponentResult SGGetVideoCompressor (
   SGChannel c,
   short *depth,
   CompressorComponent *compressor,
   CodecQ *spatialQuality,
   CodecQ *temporalQuality,
   long *keyFrameRate
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

depth

A pointer to a field that is to receive the depth at which the image is likely to be viewed. Image compressor components may use the depth as an indication of the color or grayscale resolution of the compressed images. Return the depth value currently in use by your channel component. If this parameter is set to NIL, the sequence grabber component is not interested in this information.

compressor

A pointer to a field that is to receive an image compressor identifier. Return the identifier that corresponds to the image compressor your channel is using. If this parameter is set to NIL, the sequence grabber component is not interested in this information.

spatialQuality

A pointer to a field that is to receive the desired compressed image quality. Return the current quality value. If this parameter is set to NIL, the sequence grabber component is not interested in this information. See these constants:

  • codecMinQuality

  • codecLowQuality

  • codecNormalQuality

  • codecHighQuality

  • codecMaxQuality

  • codecLosslessQuality

temporalQuality

A pointer to a field that is to receive the desired temporal quality of the sequence. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Return the current temporal quality value. If this parameter is set to NIL, the sequence grabber component is not interested in this information.

keyFrameRate

A pointer to a field that is to receive the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. This value controls the frequency at which the image compressor places key frames into the compressed sequence. Return the current key frame rate. If this parameter is set to NIL, the sequence grabber component is not interested in this information.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetVideoCompressorType

Determines the type of image compression that is being applied to a channel's video data.

ComponentResult SGGetVideoCompressorType (
   SGChannel c,
   OSType *compressorType
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

compressorType

A pointer to a field that is to receive information about the type of image compression to use. Return a value (see below) that corresponds to one of the image-compression types supported by the Image Compression Manager. You should use GetCodecNameList to retrieve these names, so that your application can take advantage of new compressor types that may be added in the future. See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGetVideoDigitizerComponent

Determines the video digitizer component that is providing source video to a video channel component.

ComponentInstance SGGetVideoDigitizerComponent (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

A component instance that identifies the connection between your video channel component and its video digitizer component. If your video channel component does not use a video digitizer component, set this returned value to NIL.

Discussion

This function allows the sequence grabber component to determine the video digitizer component that is providing source video to your video channel component. For example, the sequence grabber component can use this function to obtain access to the video digitizer component so that the grabber component can set the digitizer's parameters.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGetVideoRect

Determines the portion of the source video image that is to be captured.

ComponentResult SGGetVideoRect (
   SGChannel c,
   Rect *r
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

r

A pointer to a Rect structure that is to receive the dimensions of the rectangle that defines the portion of the source video image your component is going to capture.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGrabCompressComplete

Provides the default behavior for your grab-compress-complete function.

ComponentResult SGGrabCompressComplete (
   SGChannel c,
   UInt8 *queuedFrameCount,
   SGCompressInfo *ci,
   TimeRecord *tr
);

Parameters
c

The connection identifier for the channel for this operation. The sequence grabber provides this value to your grab-compress-complete function.

queuedFrameCount

A pointer to the number of queued frames yet to be done. 0 means no frames. Some VDIGs may return 2 even if more than 2 frames are available, and some will return 1 if any number more than 0 are available.

ci

A pointer to an SGCompressInfo structure. When the operation is complete, the function fills in this structure with information about the compression operation.

tr

A pointer to a TimeRecord structure. When the operation is complete, the function uses this structure to indicate when the frame was grabbed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

By setting the SGGrabCompressCompleteBottleProc callback and calling this function, your application can determine how many frames are currently queued in the VDIG, which can be useful for real-time processing.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGrabFrame

Provides the default behavior for your grab function.

ComponentResult SGGrabFrame (
   SGChannel c,
   short bufferNum
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber component provides this value to your grab function.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your grab function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGGrabFrameComplete

Provides the default behavior for your grab-complete function.

ComponentResult SGGrabFrameComplete (
   SGChannel c,
   short bufferNum,
   Boolean *done
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber provides this value to your grab-complete function.

bufferNum

Identifies the buffer. The sequence grabber provides this value to your grab-complete function.

done

A pointer to a Boolean value. The function sets this value to TRUE if the capture is complete, and sets it to FALSE if the capture is incomplete. The sequence grabber provides this pointer to your grab-complete function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGGrabPict

Lets your application obtain a Picture structure from a sequence grabber component.

ComponentResult SGGrabPict (
   SeqGrabComponent s,
   PicHandle *p,
   const Rect *bounds,
   short offscreenDepth,
   long grabPictFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

p

A pointer to a field that is to receive a handle to the Picture structure. If the function cannot create the structure, it sets this handle to NIL.

bounds

A pointer to the boundary region for the Picture structure. By default, this rectangle lies in the current graphics port. If you set the grabPictOffScreen flag in the grabPictFlags parameter to 1, the sequence grabber places the structure in an offscreen graphics world. In this case, the rectangle is interpreted in that offscreen world.

offscreenDepth

The pixel depth for the offscreen graphics world. This parameter is typically set to 0, which chooses the best available depth. If you set the grabPictOffScreen flag in the grabPictFlags parameter to 1, the sequence grabber places the Picture structure in an offscreen graphics world. You specify the pixel depth of this offscreen graphics world with this parameter. If you are displaying the picture, this parameter is ignored.

grabPictFlags

Contains flags (see below) that control the operation. See these constants:

  • grabPictOffScreen

  • grabPictIgnoreClip

  • grabPictCurrentImage

Return Value

See Error Codes. Returns noErr if there is no error.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGHandleUpdateEvent

Requests that a sequence grabber handle an update event.

ComponentResult SGHandleUpdateEvent (
   SeqGrabComponent s,
   const EventRecord *event,
   Boolean *handled
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

event

A pointer to an EventRecord structure.

handled

A pointer to a Boolean that returns TRUE if the event was handled, FALSE otherwise.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGIdle

Provides processing time for sequence grabber components.

ComponentResult SGIdle (
   SeqGrabComponent s
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

After starting a preview or record operation, the application calls this function as often as possible. The sequence grabber component then calls your SGIdle function. This continues until the calling application stops the operation by calling SGStop.Your SGIdle function reports several status and error conditions by means of its result code. If your component returns a nonzero result code during a record operation, the application should call SGStop so that the sequence grabber component can store the data it has collected.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGInitChannel

Initializes a channel component.

ComponentResult SGInitChannel (
   SGChannel c,
   SeqGrabComponent owner
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

owner

Identifies the sequence grabber component that has been connected to your channel component. You should save this value so that your channel component can call the utility functions that are provided by the sequence grabber component.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGInitialize

Initializes the sequence grabber component.

ComponentResult SGInitialize (
   SeqGrabComponent s
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Before you can call this function you must establish a connection to the sequence grabber component. Use OpenDefaultComponent or OpenComponent to establish a component connection, as shown below:

// SGInitialize coding example
// See "Discovering QuickTime," page 262
SeqGrabComponent MakeMySequenceGrabber (WindowRef pMacWnd)
{
    SeqGrabComponent    seqGrab =NIL;
    OSErr               nErr =noErr;
    // open the default sequence grabber
    seqGrab =OpenDefaultComponent(SeqGrabComponentType, 0);
    if (seqGrab !=NIL) {
        // initialize the default sequence grabber component
        nErr =SGInitialize(seqGrab);
        if (nErr ==noErr) {
        // set its graphics world to the specified window
            nErr =SGSetGWorld(seqGrab, (CGrafPtr)pMacWnd, NIL);
        }
    }
    if (nErr && (seqGrab !=NIL)) {    // clean up on failure
        CloseComponent(seqGrab);
        seqGrab =NIL;
    }
    return seqGrab;
}
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGNewChannel

Creates a sequence grabber channel and assigns a channel component to the channel.

ComponentResult SGNewChannel (
   SeqGrabComponent s,
   OSType channelType,
   SGChannel *ref
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

channelType

The type of channel to open (see below). This value corresponds to the component subtype value of the channel component. See these constants:

  • VideoMediaType

  • SoundMediaType

ref

A pointer to the frameChannel field in the SeqGrabFrameInfo structure that is to receive a reference to the channel that is added to the sequence grabber component. If the sequence grabber component successfully locates and connects to an appropriate channel component, the sequence grabber component returns a reference to the channel component into this field.

Return Value

See Error Codes. If the sequence grabber component cannot open a connection, it sets the result code to a nonzero value. It returns noErr if there is no error.

Discussion

The channel component is responsible for providing digitized data to the sequence grabber component. You specify the type of channel component to be added to the sequence grabber component, as shown in the following sample code:

// SGNewChannel coding example
// See "Discovering QuickTime," page 263
void MakeMyGrabChannels (SeqGrabComponent    seqGrab,
                            SGChannel        *sgchanVideo,
                            SGChannel        *sgchanSound,
                            const Rect       *rect,
                            Boolean          bWillRecord)
{
    OSErr           nErr;
    long            lUsage;
    // figure out the usage
    lUsage =seqGrabPreview;                // always previewing
    if (bWillRecord)
        lUsage |=seqGrabRecord;            // sometimes recording
    // create a video channel
    nErr =SGNewChannel(seqGrab, VideoMediaType, sgchanVideo);
    if (nErr ==noErr) {
        // set boundaries for new video channel
        nErr =SGSetChannelBounds(*sgchanVideo, rect);
        // set usage for new video channel
        if (nErr ==noErr)
            nErr =SGSetChannelUsage(*sgchanVideo, lUsage |
                                        seqGrabPlayDuringRecord);
        if (nErr !=noErr) {
            // clean up on failure
            SGDisposeChannel(seqGrab, *sgchanVideo);
            *sgchanVideo =NIL;
        }
    }
    // create a sound channel
    nErr =SGNewChannel(seqGrab, SoundMediaType, sgchanSound);
    if (nErr ==noErr) {
        // set usage of new sound channel
        nErr =SGSetChannelUsage(*sgchanSound, lUsage);
        if (nErr !=noErr) {
            // clean up on failure
            SGDisposeChannel(seqGrab, *sgchanSound);
            *sgchanSound =NIL;
        }
    }
}
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGNewChannelFromComponent

Creates a sequence grabber channel and assigns a channel component to the channel.

ComponentResult SGNewChannelFromComponent (
   SeqGrabComponent s,
   SGChannel *newChannel,
   Component sgChannelComponent
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

newChannel

A pointer to a channel component that is to receive a reference to the channel that is added to the sequence grabber component. If the sequence grabber component successfully locates and connects to the specified channel component, the sequence grabber component returns a reference to the channel component into this field.

sgChannelComponent

Identifies the channel component to use. You supply a component ID value to the sequence grabber. The sequence grabber then opens a connection to that channel component and returns your connection ID in the field specified by the newChannel parameter. You may obtain a component ID value by calling FindNextComponent.

Return Value

See Error Codes. If the sequence grabber component cannot open a connection, it sets the result code to a nonzero value. It returns noErr if there is no error.

Discussion

This function is similar to SGNewChannel, except that this function allows you to specify a particular component rather than just a component subtype value.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGNewOutput

Creates a new sequence grabber output.

ComponentResult SGNewOutput (
   SeqGrabComponent s,
   Handle dataRef,
   OSType dataRefType,
   long whereFlags,
   SGOutput *sgOut
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

dataRef

A handle to the destination container.

dataRefType

The type of data reference; see Data References. If the data reference is an alias, you must set the parameter to rAliasType.

whereFlags

Flags (see below) that control the record operation. You must set either seqGrabToDisk or seqGrabToMemory to 1. Set unused flags to 0. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

sgOut

A pointer to a sequence grabber output. The sequence grabber component returns an output identifier that you can use with other sequence grabber component functions.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Once you have created the sequence grabber output, you can use SGSetChannelOutput to assign the output to a sequence grabber channel.

Version Notes

A sequence grabber output ties a sequence grabber channel to a specified data reference for the output of captured data. If you are capturing to a single movie file, you can continue to use SGSetDataOutput or SGSetDataRef to specify the sequence grabber's destination. However, if you want to capture movie data into several different files or data references, you must use sequence grabber outputs to do so. Even if you are using outputs, you must still use SGSetDataOutput or SGSetDataRef to identify where the sequence grabber should create the movie resource. You are responsible for creating outputs, assigning them to sequence grabber channels, and disposing of them when you are done.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGPanelCanRun

Lets a sequence grabber component determine whether a panel component can work with the current sequence grabber channel component.

ComponentResult SGPanelCanRun (
   SeqGrabComponent s,
   SGChannel c
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. The sequence grabber component provides you with a connection to the channel component in question. You must determine whether your panel component can operate with this channel component and its associated channel hardware.

Return Value

If your component can work with the specified channel, return a result code of noErr. Otherwise, return an appropriate sequence grabber or sequence grabber channel component result code. See Error Codes.

Discussion

Set the channelFlagHasDependency flag in the ComponentDescription structure of your sequence grabber panel component to cause the sequence grabber component to call this function. Your component should query the channel component to determine whether you can operate with it. You may want to use channel component functions to determine the characteristics of the digitization source attached to the channel.

Special Considerations

If your panel component can only support a limited number of connections, you should regulate the number of active connections through this function. Return a nonzero result code to indicate to the sequence grabber that your panel component cannot support the current connection.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelEvent

Lets a component receive and process dialog events.

ComponentResult SGPanelEvent (
   SeqGrabComponent s,
   SGChannel c,
   DialogRef d,
   short itemOffset,
   const EventRecord *theEvent,
   short *itemHit,
   Boolean *handled
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

d

A dialog pointer identifying the settings dialog box.

itemOffset

The offset to your panel's first item in the dialog box.

theEvent

A pointer to an EventRecord structure. This structure contains information identifying the nature of the event.

itemHit

A pointer to a field that is to receive the item number in cases where your component handles the event. The number returned is an absolute, not a relative number, so it must be offset by the itemOffset parameter.

handled

A pointer to a Boolean value. Set this Boolean value to TRUE if you handle the event; set it to FALSE if you do not.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelGetDitl

Lets a sequence grabber component determine the dialog items managed by your panel component.

ComponentResult SGPanelGetDitl (
   SeqGrabComponent s,
   Handle *ditl
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

ditl

A pointer to a handle provided by the sequence grabber component. Your component returns the item list in this handle. Your component should resize this handle as appropriate. The sequence grabber component will dispose of this handle after retrieving the item list, so make sure that the item list is not stored in a resource.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The sequence grabber uses the information returned by this function to build a sequence grabber settings dialog box for the user. The sequence grabber component will open your resource file before calling this function, unless you have instructed the sequence grabber component not to open your resource file by setting the channelFlagDontOpenResFile flag in your your panel component's ComponentDescription structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelGetDITLForSize

Returns user interface elements that fit within a specified size panel.

ComponentResult SGPanelGetDITLForSize (
   SeqGrabComponent s,
   Handle *ditl,
   Point *requestedSize
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

ditl

A pointer to a handle provided by the sequence grabber component. Your panel component returns the dialog item list in this handle. Your component should resize this handle as appropriate. The sequence grabber component will dispose of this handle after retrieving the item list, so make sure that the item list is not stored in a resource.

requestedSize

The size of the panel, or constants (see below). The sequence grabber will interpolate the panel elements between the two sizes if just the constants are returned. See these constants:

  • kSGSmallestDITLSize

  • kSGLargestDITLSize

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This routine is used to retrieve user interface elements that fit within a specified size panel. If it is not implemented, the sequenced grabber will assume that your panel does not have resizable user interface elements.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

SGPanelGetSettings

Retrieves a panel's current settings for a sequence grabber component.

ComponentResult SGPanelGetSettings (
   SeqGrabComponent s,
   SGChannel c,
   UserData *ud,
   long flags
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

ud

A pointer to a UserDataRecord structure. Your component is responsible for creating a new structure and returning it by means of this pointer. Your component is not responsible for disposing of the structure. These settings may be stored as part of a larger sequence grabber configuration and may be stored for a long period of time. Therefore, you should not store values that may change without your knowledge (such as component ID or connection values). You are free to format the data in user data items any way you desire.

flags

Reserved for future use.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Make sure your component can retrieve the settings information from the user data item when this function is called. You may choose to format the data in such a way that other components can parse it easily, thus allowing your component to operate with other panel components.

Special Considerations

You create new user data items by calling NewUserData. You may then use other Movie Toolbox functions to manipulate the user data items.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelGetTitle

Gets the displayed title of a sequence grabber panel.

ComponentResult SGPanelGetTitle (
   SeqGrabComponent s,
   Str255 title
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

title

A string containing the panel's title.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelInstall

Installs added items in a sequence grabber settings dialog box before the dialog box is displayed to the user.

ComponentResult SGPanelInstall (
   SeqGrabComponent s,
   SGChannel c,
   DialogRef d,
   short itemOffset
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

d

A dialog pointer identifying the settings dialog box. Your component may use this value to manage its part of the dialog box.

itemOffset

The offset to your panel's first item in the dialog box. Because sequence grabber components build your dialog items into a larger dialog box containing other items, this value may be different each time your panel component is installed; do not rely on it being the same.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

A sequence grabber component calls this function just before displaying the dialog box to the user. The sequence grabber provides you with information identifying the channel that your panel is to configure, the dialog box, and the offset of your panel's items into the dialog box. You may use this opportunity to set default dialog values or to initialize your control values.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelItem

Receives and processes mouse clicks in the sequence grabber settings dialog box.

ComponentResult SGPanelItem (
   SeqGrabComponent s,
   SGChannel c,
   DialogRef d,
   short itemOffset,
   short itemNum
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

d

A dialog pointer identifying the settings dialog box.

itemOffset

The offset to your panel's first item in the dialog box.

itemNum

The item number of the dialog item selected by the user. The sequence grabber provides an absolute item number. It is your responsibility to adjust this value to account for the offset to your panel's first item in the dialog box.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

A sequence grabber component calls this function whenever the user clicks an item in the settings dialog box. Your component may then perform whatever processing is appropriate, depending upon the item number.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelRemove

Removes a panel from the sequence grabber settings dialog box.

ComponentResult SGPanelRemove (
   SeqGrabComponent s,
   SGChannel c,
   DialogRef d,
   short itemOffset
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

d

A dialog pointer identifying the settings dialog box.

itemOffset

The offset to your panel's first item in the dialog box.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

A sequence grabber component calls this function just before removing your items from the settings dialog box. The sequence grabber provides you with information identifying the channel your panel is to configure, the dialog box, and the offset of your panel's items into the dialog box. You may use this opportunity to save any changes you may have made to the dialog box or to retrieve the contents of text items.

Special Considerations

If the sequence grabber opened your resource file, it will still be open when it calls this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelSetEventFilter

Sets the event filter callback for a sequence grabber panel component.

ComponentResult SGPanelSetEventFilter (
   SeqGrabComponent s,
   SGModalFilterUPP proc,
   long refCon
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

proc

An SGModalFilterProc callback.

refCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelSetGrabber

Identifies a sequence grabber component to a panel component.

ComponentResult SGPanelSetGrabber (
   SeqGrabComponent s,
   SeqGrabComponent sg
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component.

sg

Identifies a connection to the sequence grabber component that is using your panel component. Your component may use this connection to call sequence grabber component functions.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

A sequence grabber component calls this function in order to identify itself to your panel component. Your component can use the provided connection to call sequence grabber functions, either to determine the characteristics of the current capture operation or to alter those characteristics.

Special Considerations

This is typically the first function a sequence grabber component calls after opening your panel component.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelSetResFile

Lets the sequence grabber pass a resource file's reference number.

ComponentResult SGPanelSetResFile (
   SeqGrabComponent s,
   short resRef
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

resRef

A reference number that identifies your component's resource file. After it closes your resource file, the sequence grabber component calls this function and sets this value to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

A sequence grabber component calls this function to pass you your component's resource file reference number. By default, the sequence grabber component opens your component's resource file for you. You can use this reference number to retrieve resources from your resource file. The sequence grabber component also calls this function when it closes your component's resource file. In this case, it sets the resRef parameter to 0. The sequence grabber component may close your resource file at any time; you should not count on any particular calling sequence. If you do not want the sequence grabber component to open your resource file, set the channelFlagDontOpenResFile flag in your panel component's ComponentDescription structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelSetSettings

Restores a panel's current settings for a sequence grabber component.

ComponentResult SGPanelSetSettings (
   SeqGrabComponent s,
   SGChannel c,
   UserData ud,
   long flags
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

ud

Identifies a UserDataRecord structure that contains new settings information for your panel. Your component must not dispose of this structure.

flags

Reserved for future use.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your component originally creates the settings information when the sequence grabber calls SGPanelGetSettings. The sequence grabber passes this configuration information back to you in the ud parameter to this function. Your component should parse the configuration information and use it to establish your panel's current settings. Note that your component may not be able to accommodate the original settings. For example, because the settings may have been stored for some time, the hardware environment may not be able to support the values in the settings. You should try to make your new settings match the original settings as closely as possible. If you cannot get close enough, return an appropriate sequence grabber or sequence grabber channel result code.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPanelValidateInput

Validates the contents of the user dialog box for a sequence grabber component.

ComponentResult SGPanelValidateInput (
   SeqGrabComponent s,
   Boolean *ok
);

Parameters
s

Identifies the sequence grabber component's connection to your panel component. See SGPanelSetGrabber.

ok

A pointer to a Boolean value. Set this value to TRUE if the settings are OK; otherwise, set it to FALSE.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The sequence grabber calls this function when the user clicks the OK button. If the user clicks the Cancel button, the sequence grabber does not call this function. You indicate whether the settings are acceptable by setting the Boolean value referred to by the ok parameter. If you set this value to FALSE, the sequence grabber component ignores the OK button in the dialog box.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGPause

Suspends or restarts a sequence grabber record or preview operation.

ComponentResult SGPause (
   SeqGrabComponent s,
   Byte pause
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

pause

A constant (see below) that instructs your component to suspend or restart the current operation. See these constants:

  • seqGrabUnpause

  • seqGrabPause

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your component should not release any system resources or temporary memory associated with the current operation. You should be ready to restart the operation immediately.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGPrepare

Instructs a sequence grabber to get ready to begin a preview or record operation.

ComponentResult SGPrepare (
   SeqGrabComponent s,
   Boolean prepareForPreview,
   Boolean prepareForRecord
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

prepareForPreview

The sequence grabber component sets this parameter to TRUE to prepare for a preview operation. The sequence grabber component may set both the prepareForPreview and prepareForRecord parameters to TRUE.

prepareForRecord

The sequence grabber component sets this parameter to TRUE to prepare for a record operation. The sequence grabber component may set both the prepareForPreview and prepareForRecord parameters to TRUE.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If you do not call this function before starting a record or preview operation, the sequence grabber component makes these preparations when you start the operation. You cannot call this function after you start a preview or record operation. If you call this function without subsequently starting a record or preview operation, you should call SGRelease. This allows the sequence grabber component to release any system resources it allocated when you called this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGRelease

Instructs the sequence grabber to release any system resources it allocated when you called SGPrepare.

ComponentResult SGRelease (
   SeqGrabComponent s
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You cannot call this function during a record or preview operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetAdditionalSoundRates

Specifies a list of sound sample rates to be included in the sequence grabber's sound settings dialog box.

ComponentResult SGSetAdditionalSoundRates (
   SGChannel c,
   Handle rates
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

rates

A handle containing a list of unsigned 32-bit fixed-point values. The sequence grabber channel determines the number of sample rates contained in the handle, based on the size of the handle. If any of the requested rates are not supported directly by the available sound capture hardware, sound will be captured at one of the available hardware rates and then converted in software to the requested rate.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The sequence grabber channel makes a copy of the additional rates handle, so your application can immediately dispose of it after making this call.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelBounds

Specifies a channel's display boundary rectangle.

ComponentResult SGSetChannelBounds (
   SGChannel c,
   const Rect *bounds
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bounds

A pointer to a Rect structure that defines your channel's display boundary rectangle.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelClip

Sets a channel's clipping region.

ComponentResult SGSetChannelClip (
   SGChannel c,
   RgnHandle theClip
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

theClip

A handle to the new clipping region. You should make a copy of this region; the application may dispose of the region immediately.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelDevice

Assigns a device to a channel.

ComponentResult SGSetChannelDevice (
   SGChannel c,
   StringPtr name
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

name

A pointer to the device's name string. This name is contained in the name field of the appropriate SGDeviceName structure in the SGDeviceListRecord structure that your channel component returns to the SGGetChannelDeviceList function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetChannelDeviceInput

Undocumented

ComponentResult SGSetChannelDeviceInput (
   SGChannel c,
   short inInputNumber
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

inInputNumber

Identifies a device. The value of this field corresponds to the appropriate entry in the device name array defined by the entry field of a SGDeviceListRecord structure. This value is zero-relative; the first entry has an index number of 0, the second's value is 1, and so on.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

SGSetChannelMatrix

Sets a channel's display transformation matrix.

ComponentResult SGSetChannelMatrix (
   SGChannel c,
   const MatrixRecord *m
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

m

A pointer to a MatrixRecord structure. This parameter is set to NIL to select the identity matrix.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelMaxFrames

Limits the number of frames that the sequence grabber will capture from a specified channel.

ComponentResult SGSetChannelMaxFrames (
   SGChannel c,
   long frameCount
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

frameCount

The maximum number of frames to capture during the preview or record operation. The sequence grabber component sets this parameter to -1 to remove the limit.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You may use this function only after you have prepared the sequence grabber component for a record operation or during an active record operation.

Special Considerations

Note that sequence grabber components clear this value when you prepare for a record operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetChannelOutput

Assigns an output to a channel.

ComponentResult SGSetChannelOutput (
   SeqGrabComponent s,
   SGChannel c,
   SGOutput sgOut
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function to assign an output to a channel. One output may be assigned to one or more channels. Note that when you call SGSetDataRef or SGSetDataOutput the sequence grabber component sets every channel to the specified file or container. If you want to use different outputs, you must use this function to assign the channels appropriately.

Version Notes

A sequence grabber output ties a sequence grabber channel to a specified data reference for the output of captured data. If you are capturing to a single movie file, you can continue to use SGSetDataOutput or SGSetDataRef to specify the sequence grabber's destination. However, if you want to capture movie data into several different files or data references, you must use sequence grabber outputs to do so. Even if you are using outputs, you must still use SGSetDataOutput or SGSetDataRef to identify where the sequence grabber should create the movie resource. You are responsible for creating outputs, assigning them to sequence grabber channels, and disposing of them when you are done.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelPlayFlags

Adjusts the speed and quality with which the sequence grabber displays data from a channel.

ComponentResult SGSetChannelPlayFlags (
   SGChannel c,
   long playFlags
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

playFlags

A long integer that contains flags (see below) that influence channel playback. A sequence grabber component must use one of these values. See these constants:

  • channelPlayNormal

  • channelPlayFast

  • channelPlayHighQuality

  • channelPlayAllData

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelRefCon

Sets the value of a reference constant that is passed to your callback functions for channel components.

ComponentResult SGSetChannelRefCon (
   SGChannel c,
   long refCon
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

refCon

A reference constant value that your component should pass to the callback functions that have been assigned to this channel. Use this parameter to point to a data structure containing any information your callbacks need.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelSettings

Configures a sequence grabber channel.

ComponentResult SGSetChannelSettings (
   SeqGrabComponent s,
   SGChannel c,
   UserData ud,
   long flags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

ud

A UserDataRecord structure that contains the configuration information to be used by the channel component.

flags

Reserved for Apple. Set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelSettingsStateChanging

Tells a sequence grabber channel of the beginning and end of a group of setting calls.

ComponentResult SGSetChannelSettingsStateChanging (
   SGChannel c,
   UInt32 inFlags
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

inFlags

Constants (see below) that determine whether this function is being called at the beginning or end of a series of channel setting calls. See these constants:

  • sgSetSettingsBegin

  • sgSetSettingsEnd

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You can use this call to bracket a group of sequence grabber channel configuration calls, giving downstream components an opportunity to deal with the entire settings change in one operation.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

SGSetChannelUsage

Specifies how a channel is to be used by the sequence grabber component.

ComponentResult SGSetChannelUsage (
   SGChannel c,
   long usage
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

usage

Contains flags (see below) specifying how your channel is to be used. The sequence grabber component may set more than one of these flags to 1. It sets unused flags to 0. See these constants:

  • seqGrabRecord

  • seqGrabPreview

  • seqGrabPlayDuringRecord

  • seqGrabLowLatencyCapture

  • seqGrabAlwaysUseTimeBase

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier. Flags added in QuickTime 6.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetChannelVolume

Sets a channel's sound volume.

ComponentResult SGSetChannelVolume (
   SGChannel c,
   short volume
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

volume

The volume setting of your channel represented as a 16-bit, fixed-point number. The high-order 8 bits contain the integer part of the value; the low-order 8 bits contain the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetCompressBuffer

Allows the sequence grabber component to direct your component to create a filter buffer for your video channel.

ComponentResult SGSetCompressBuffer (
   SGChannel c,
   short depth,
   const Rect *compressSize
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

depth

The pixel depth of the filter buffer. If the sequence grabber sets this parameter to 0, use the depth of the video buffer, which the sequence grabber sets with SGSetChannelBounds.

compressSize

A pointer to a Rect structure that contains the dimensions of the filter buffer. This buffer should be larger than the destination buffer. To stop filtering the input source video data, the sequence grabber component sets this parameter to NIL or it sets the coordinates of this rectangle to 0 (specifying an empty rectangle).

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

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. Logically, this buffer sits between the source video buffer and the destination rectangle you set with the SGSetChannelBounds.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetDataOutput

Specifies the movie file and options for a sequence grabber record operation.

ComponentResult SGSetDataOutput (
   SeqGrabComponent s,
   const FSSpec *movieFile,
   long whereFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

movieFile

A pointer to the FSSpec structure that identifies the movie file for this record operation.

whereFlags

Contains flags (see below) that control the record operation. You must set either seqGrabToDisk flag or seqGrabToMemory to 1. Set unused flags to 0. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetDataProc

Specifies a data function for use by the sequence grabber.

ComponentResult SGSetDataProc (
   SeqGrabComponent s,
   SGDataUPP proc,
   long refCon
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

proc

A pointer to your data function. To remove your data function, set this parameter to NIL.

refCon

A reference constant. The sequence grabber provides this value to your data callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetDataRef

Specifies the destination data reference for a record operation.

ComponentResult SGSetDataRef (
   SeqGrabComponent s,
   Handle dataRef,
   OSType dataRefType,
   long whereFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

dataRef

A handle to the information that identifies the destination container.

dataRefType

The type of data reference. If the data reference is an alias, you must set the parameter to rAliasType.

whereFlags

Contains flags (see below) that control the record operation. You must set either seqGrabToDisk or seqGrabToMemory to 1. Set unused flags to 0. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to specify the destination for a record operation using a data reference, and to specify other options that govern the operation. This function is similar to SGSetDataOutput, and provides you with an alternative way to specify the destination.

Special Considerations

If you are performing a preview operation, you don't need to use this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetFlags

Passes control information about the current operation to the sequence grabber component.

ComponentResult SGSetFlags (
   SeqGrabComponent s,
   long sgFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgFlags

Contains a flag (see below) to tell the sequence grabber if you are performing a controlled grab using a frame-addressable source device. See these constants:

  • sgFlagControlledGrab

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetFontName

Sets the name of the font to be used to display text for a text channel component.

ComponentResult SGSetFontName (
   SGChannel c,
   StringPtr pstr
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

pstr

A pointer to a Pascal string containing the name of the font.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If the specified font is available on the system, the text channel uses the font to display text. If the specified font is not available, the text channel uses the default system font. For more information about fonts, see Inside Macintosh: Text.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetFontSize

Sets the font size to be used to display text for a text channel component.

ComponentResult SGSetFontSize (
   SGChannel c,
   short fontSize
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

fontSize

The point size of the font. This value must be a positive integer.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetFrameRate

Specifies a video channel's frame rate for recording.

ComponentResult SGSetFrameRate (
   SGChannel c,
   Fixed frameRate
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

frameRate

The desired frame rate. If this parameter is set to 0, use your channel's default frame rate. Typically, this corresponds to the fastest rate that your channel can support.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetGWorld

Establishes the graphics port and device for a sequence grabber component.

ComponentResult SGSetGWorld (
   SeqGrabComponent s,
   CGrafPtr gp,
   GDHandle gd
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

gp

The destination graphics port, which must be a color graphics port. The sequence grabber component always sets this parameter to a valid value. To use the current graphics port, the parameter is set to NIL.

gd

A handle to the destination graphics device. The sequence grabber component always sets this parameter to a valid value.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You must call this function if you are working with any channels that collect visual data. If you are working only with data that has no visual representation, you do not need to call this function. The sequence grabber component performs this operation implicitly when you call SGInitialize and the component uses your application's current graphics port. To set it to a specified window, use code such as the following:

// SGSetGWorld coding example
// See "Discovering QuickTime," page 262
SeqGrabComponent MakeMySequenceGrabber (WindowRef pMacWnd)
{
    SeqGrabComponent    seqGrab =NIL;
    OSErr               nErr =noErr;
    // open the default sequence grabber
    seqGrab =OpenDefaultComponent(SeqGrabComponentType, 0);
    if (seqGrab !=NIL) {
        // initialize the default sequence grabber component
        nErr =SGInitialize(seqGrab);
        if (nErr ==noErr) {
        // set its graphics world to the specified window
            nErr =SGSetGWorld(seqGrab, (CGrafPtr)pMacWnd, NIL);
        }
    }
    if (nErr && (seqGrab !=NIL)) {    // clean up on failure
        CloseComponent(seqGrab);
        seqGrab =NIL;
    }
    return seqGrab;
}
Special Considerations

You cannot call this function during a record or preview operation, or after you have prepared the sequence grabber component for a record or preview operation by calling SGPrepare. The window in which the sequence grabber is to draw video frames as defined by this function must be visible before you call SGPrepare; otherwise, the sequence grabber does not display the frames properly.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetInstrument

Sets a tone description for a music sequence grabber channel.

ComponentResult SGSetInstrument (
   SGChannel c,
   ToneDescription *td
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

td

Pointer to a ToneDescription structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetJustification

Sets the alignment to be used to display text for a text channel component.

ComponentResult SGSetJustification (
   SGChannel c,
   short just
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

just

A constant (see below) that represents the text alignment. See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You call this function to specify the alignment to be used for text in a text track. The text channel component justifies text relative to the boundaries of its text box.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetMaximumRecordTime

Limits the duration of a record operation

ComponentResult SGSetMaximumRecordTime (
   SeqGrabComponent s,
   unsigned long ticks
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

ticks

The maximum duration for the record operation, in system ticks (sixtieths of a second). Set this parameter to 0 to remove the time limit from the operation.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

By default, there is no time limit on a record operation. If you do not set a limit, a record operation will run until it exhausts the Operating System resources or you call SGStop. Memory and disk space are the two major limiting factors.

Special Considerations

You must call this function before you start a sequence grabber record operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetOutputFlags

Configures an existing sequence grabber output.

ComponentResult SGSetOutputFlags (
   SeqGrabComponent s,
   SGOutput sgOut,
   long whereFlags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the sequence grabber output for this operation. You obtain this identifier by calling SGNewOutput.

whereFlags

Contains flags (see below) that control the record operation. You must set either seqGrabToDisk or seqGrabToMemory to 1. Set unused flags to 0. See these constants:

  • seqGrabToDisk

  • seqGrabToMemory

  • seqGrabDontUseTempMemory

  • seqGrabAppendToFile

  • seqGrabDontAddMovieResource

  • seqGrabDontMakeMovie

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function lets you configure an existing sequence grabber output.

Version Notes

A sequence grabber output ties a sequence grabber channel to a specified data reference for the output of captured data. If you are capturing to a single movie file, you can continue to use SGSetDataOutput or SGSetDataRef to specify the sequence grabber's destination. However, if you want to capture movie data into several different files or data references, you must use sequence grabber outputs to do so. Even if you are using outputs, you must still use SGSetDataOutput or SGSetDataRef to identify where the sequence grabber should create the movie resource. You are responsible for creating outputs, assigning them to sequence grabber channels, and disposing of them when you are done.

Availability
Declared In
QuickTimeComponents.h

SGSetOutputMaximumOffset

Specifies the maximum offset for data written to a specified sequence grabber output.

ComponentResult SGSetOutputMaximumOffset (
   SeqGrabComponent s,
   SGOutput sgOut,
   const wide *maxOffset
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

Identifies the current sequence grabber output. You obtain this identifier by calling SGNewOutput.

maxOffset

A pointer to the value of the maximum offset for data written to this output.

Return Value

See Error Codes. Returns an error if no more outputs are available. Returns noErr if there is no error.

Discussion

If an attempt is made to write data beyond the maximum offset, the sequence grabber switches to the next output specified by SGSetOutputNextOutput. If no more outputs are available, an end-of-file error is returned and recording ends.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetOutputNextOutput

Specifies the order in which sequence grabber outputs should be used.

ComponentResult SGSetOutputNextOutput (
   SeqGrabComponent s,
   SGOutput sgOut,
   SGOutput nextOut
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

sgOut

The current output to use. When a new output is created, its nextOut is set to NIL.

nextOut

The next output to be used. To specify that this is the last output, set this value to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function should not be called while recording.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetPreferredPacketSize

Sets the preferred packet size for the sequence grabber channel component.

ComponentResult SGSetPreferredPacketSize (
   SGChannel c,
   long preferredPacketSizeInBytes
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

preferredPacketSizeInBytes

The preferred packet size in bytes.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

This function was added in QuickTime 2.5 to support video conferencing applications.

Availability
Declared In
QuickTimeComponents.h

SGSetSettings

Configures a sequence grabber and its channels.

ComponentResult SGSetSettings (
   SeqGrabComponent s,
   UserData ud,
   long flags
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

ud

A UserDataRecord structure that contains the configuration information to be used by the sequence grabber.

flags

Reserved for Apple. Set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The sequence grabber disposes of any of its current channels before applying this configuration information. It then opens connections to new channels as appropriate.

Special Considerations

You can restore saved settings by using NewUserDataFromHandle.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetSettingsSummary

Sets the summary of sequence grabber settings that is displayed in the lower left corner of the sequence grabber dialog.

ComponentResult SGSetSettingsSummary (
   SeqGrabComponent s,
   Handle summaryText
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

summaryText

A handle to the summary text.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This routine supplies a handle (no length byte) that defines a user readable summary of the state of the user's sequence grabber settings.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

SGSetSoundInputDriver

Assigns a sound input device to a sound channel.

ComponentResult SGSetSoundInputDriver (
   SGChannel c,
   ConstStr255Param driverName
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

driverName

The name of the sound input device. This is a Pascal string, and it must correspond to a valid sound input device.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetSoundInputParameters

Sets various parameters that relate to sound recording.

ComponentResult SGSetSoundInputParameters (
   SGChannel c,
   short sampleSize,
   short numChannels,
   OSType compressionType
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

sampleSize

The number of bits in each sound sample. This field is set to 8 for 8-bit sound; it is set to 16 for 16-bit sound.

numChannels

Indicates the number of sound channels to be used by the sound sample. This field is set to 1 for monaural sounds; it is set to 2 for stereo sounds.

compressionType

A constant (see below) that describes the format of the sound data. See these constants:

Return Value

See Error Codes. If your sound device cannot support a specified parameter value, return an appropriate Sound Manager result code. Return noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetSoundInputRate

Sets the rate at which the sound channel obtains its sound data.

ComponentResult SGSetSoundInputRate (
   SGChannel c,
   Fixed rate
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

rate

The rate at which your sound channel is to acquire data. This parameter specifies the number of samples your sound channel is to generate per second. If your sound channel cannot support the specified rate, use the closest available rate that you can support. If this parameter is set to 0, use your default rate.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetSoundRecordChunkSize

Controls the amount of sound data in each group of sound samples during a record operation.

ComponentResult SGSetSoundRecordChunkSize (
   SGChannel c,
   long seconds
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

seconds

A Fixed 16.16 value representing number of seconds of sound data your sound channel component is to work with at a time. Set this parameter to a negative number to specify a fraction of a second. For example, to set the duration to half a second, -0.5 is passed in.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

During record operations, the sequence grabber component and its sound channels work with groups of sound samples, referred to as chunks. By default, each chunk contains two seconds of sound data. Smaller chunks use less memory.

Special Considerations

This function may return a fraction.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetTextBackColor

Sets the background color to be used for the text box.

ComponentResult SGSetTextBackColor (
   SGChannel c,
   RGBColor *theColor
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

theColor

A pointer to an RGBColor structure that contains the new background color.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You call this function to set the background color of a text track. The text channel component uses the specified color as the background of the text box.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetTextForeColor

Sets the color to be used to display text.

ComponentResult SGSetTextForeColor (
   SGChannel c,
   RGBColor *theColor
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

theColor

A pointer to an RGBColor structure that contains the new text color.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You call this function to set the text color for a text track.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetTextReturnToSpaceValue

Determines whether the text channel component should replace return characters with spaces.

ComponentResult SGSetTextReturnToSpaceValue (
   SGChannel c,
   short rettospace
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

rettospace

Set this parameter to TRUE if the text channel should replace return characters with spaces, or FALSE otherwise.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When you capture text from a closed-caption television source, the text is composed of four lines of text of up to 32 characters each, each line separated by a return character. You can call this function to request that the text channel component replace the return characters with spaces.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSettingsDialog

Causes a sequence grabber to display its settings dialog box to the user.

ComponentResult SGSettingsDialog (
   SeqGrabComponent s,
   SGChannel c,
   short numPanels,
   ConstComponentListPtr panelList,
   long flags,
   SGModalFilterUPP proc,
   long procRefNum
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

numPanels

The number of panel components to be listed in the panel component pop-up menu. You specify the panel components with the panelList parameter. You may use these parameters to limit the user's choice of panel components. If you set this parameter to 0 and the panelList parameter to NIL, the sequence grabber lists all available panel components.

panelList

A pointer to an array of component identifiers. The sequence grabber presents only these components in the panel component pop-up menu. You specify the number of identifiers in the array with the numPanels parameter. If you set this parameter to NIL, the sequence grabber lists all available panel components.

flags

Either set this to 0 or to seqGrabSettingsPreviewOnly (see below). See these constants:

  • seqGrabSettingsPreviewOnly

proc

Specifies an SGModalFilterProc callback. Because the sequence grabber's settings dialog box is a movable modal dialog box, you must supply an event filter function to process update events in your window.

procRefNum

A reference constant to be passed to your filter callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See Error Codes. If the user clicks OK and the settings are acceptable to the panel and channel components, this function returns a result code of noErr.

Discussion

Because the user may change several channel configuration parameters, your application should retrieve new configuration information from the channel so that you can update any values you save, such as the channel's display boundaries or the channel device. In particular, the video rectangle for the channels may have to be adjusted.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetUserVideoCompressorList

Specifies the list of video compression formats to be included in the sequence grabber's video settings dialog box.

ComponentResult SGSetUserVideoCompressorList (
   SGChannel c,
   Handle compressorTypes
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

compressorTypes

A handle containing a list of OSType values indicating which video compression formats should be displayed. See Codec Identifiers. The sequence grabber channel determines the number of video compression formats contained in the handle based on the size of the handle.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function lets an application limit the number of video compression formats that will be displayed to the user. For applications using the sequence grabber for a very specific purpose, this function allows inappropriate compression choices to be filtered out.

Special Considerations

The sequence grabber channel makes a copy of the video compression formats handle. Therefore, your application can immediately dispose of the video compression formats handle after making this call.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetUseScreenBuffer

Controls whether a video channel uses an offscreen buffer.

ComponentResult SGSetUseScreenBuffer (
   SGChannel c,
   Boolean useScreenBuffer
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

useScreenBuffer

Indicates whether to use an offscreen buffer. If this parameter is set to TRUE, draw directly to the screen. If it is set to FALSE, your channel may use an offscreen buffer. If your channel cannot work with offscreen buffers, ignore this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Directing a channel to draw offscreen may be useful if you are performing transformations on the data before displaying it (such as blending it with another graphical image).

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetVideoBottlenecks

Assigns callback functions to a video channel.

ComponentResult SGSetVideoBottlenecks (
   SGChannel c,
   VideoBottles *vb
);

Parameters
c

The connection identifier for the video channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

vb

A pointer to a VideoBottles structure, which identifies the callback functions to be assigned to the video channel.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSetVideoCompressor

Specifies many of the parameters that control image compression of the video data captured by a video channel.

ComponentResult SGSetVideoCompressor (
   SGChannel c,
   short depth,
   CompressorComponent compressor,
   CodecQ spatialQuality,
   CodecQ temporalQuality,
   long keyFrameRate
);

Parameters
c

The connection identifier for the video channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

depth

The depth at which the image is likely to be viewed. Image compressors may use this as an indication of the color or grayscale resolution of the compressed images. If the sequence grabber component sets this parameter to 0, let the sequence grabber component determine the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your component can determine which depths are supported by a given compressor by examining the CodecInfo structure returned by GetCodecInfo.

compressor

The image compressor identifier. The sequence grabber component may specify a particular compressor by setting this parameter to its compressor identifier. You can obtain these identifiers from GetCodecNameList.

spatialQuality

A constant (see below) that defines the desired quality of the compressed image. See these constants:

  • codecMinQuality

  • codecLowQuality

  • codecNormalQuality

  • codecHighQuality

  • codecMaxQuality

  • codecLosslessQuality

temporalQuality

A constant (see below) that defines the desired temporal quality of the sequence. This parameter governs the level of compression the sequence grabber component desires with respect to information in successive frames in the sequence. The sequence grabber component sets this parameter to 0 to prevent the image compressor from applying temporal compression to the sequence.

keyFrameRate

The maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. The sequence grabber component uses this parameter to control the frequency with which the image compressor places key frames into the compressed sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetVideoCompressorType

Specifies the type of image compression to be applied to captured video images.

ComponentResult SGSetVideoCompressorType (
   SGChannel c,
   OSType compressorType
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

compressorType

A constant (see below) that defines the type of image compression to use. You should use GetCodecNameList to retrieve their names, so that your application can take advantage of new compressor types that may be added in the future. See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetVideoDigitizerComponent

Assigns a video digitizer component to a video channel.

ComponentResult SGSetVideoDigitizerComponent (
   SGChannel c,
   ComponentInstance vdig
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

vdig

A component instance that identifies a connection to a video digitizer component. Your video channel component should use this video digitizer component to obtain its source video data.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSetVideoRect

Specifies a part of the source video image that is to be captured by a sequence grabber component.

ComponentResult SGSetVideoRect (
   SGChannel c,
   const Rect *r
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

r

A pointer to the Rect structure that defines the portion of the source video image to be captured. This rectangle must lie within the boundaries of the source video boundary rectangle, which the sequence grabber can obtain by calling SGGetSrcVideoBounds. If you do not use this function to set a source rectangle, the sequence grabber component captures the entire video image, as defined by the source video boundary rectangle.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You cannot call this function during a record operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGSortDeviceList

Sorts a device list alphabetically.

ComponentResult SGSortDeviceList (
   SeqGrabComponent s,
   SGDeviceList list
);

Parameters
s

The component instance that identifies your connection to the sequence grabber component. You obtain this value from OpenDefaultComponent or OpenComponent.

list

A pointer to a pointer to an SGDeviceListRecord structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGSoundInputDriverChanged

Notifies the sequence grabber component whenever you change the configuration of a sound channel's sound input device.

ComponentResult SGSoundInputDriverChanged (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGStartPreview

Instructs the sequence grabber to begin processing data from its channels.

ComponentResult SGStartPreview (
   SeqGrabComponent s
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your channel component should immediately present the data to the user in the appropriate format, according to your channel's configuration. Display video data in the destination display region; play sound data at the specified volume settings.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGStartRecord

Instructs the sequence grabber component to begin collecting data from its channels.

ComponentResult SGStartRecord (
   SeqGrabComponent s
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGStop

Stops a preview or record operation.

ComponentResult SGStop (
   SeqGrabComponent s
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

It is dangerous to allow an update event to occur during recording. Many digitizers capture directly to the screen, and an update event will result in data loss.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGTransferFrameForCompress

Provides the default behavior for your transfer-frame function.

ComponentResult SGTransferFrameForCompress (
   SGChannel c,
   short bufferNum,
   const MatrixRecord *mp,
   RgnHandle clipRgn
);

Parameters
c

The reference that identifies the channel for this operation. The sequence grabber component provides this value to your transfer-frame function.

bufferNum

Identifies the buffer. The sequence grabber component provides this value to your transfer-frame function.

mp

A pointer to a MatrixRecord structure for the transfer operation. If there is no matrix for the operation, set this parameter to NIL.

clipRgn

A handle to a MacRegion structure that defines the clipping region for the destination image. This region is defined in the destination coordinate system. If there is no clipping region, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGUpdate

Informs your component about update events, to update its display.

ComponentResult SGUpdate (
   SeqGrabComponent s,
   RgnHandle updateRgn
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

updateRgn

Indicates the part of the window that has been changed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Applications can determine the part of the window that has been changed by examining the appropriate window record. For example, they may call the sequence grabber in this manner:

SGUpdate (theSG, ((WindowPeek)updateWindow)->
updateRgn);
Special Considerations

Your application should avoid drawing where the sequence grabber is displaying video. Doing so may cause some video digitizer components to stop displaying video.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SGVideoDigitizerChanged

Notifies the sequence grabber component whenever you change the configuration of a video channel's video digitizer.

ComponentResult SGVideoDigitizerChanged (
   SGChannel c
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

It is very important to notify the sequence grabber of any configuration changes you make.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGWriteExtendedMovieData

Allows your channel component to add data to a movie.

ComponentResult SGWriteExtendedMovieData (
   SeqGrabComponent s,
   SGChannel c,
   Ptr p,
   long len,
   wide *offset,
   SGOutput *sgOut
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

p

The location of the data to be added to the movie.

len

The number of bytes of data to be added to the movie.

offset

A pointer to a wide integer that receives the offset to the new data in the movie. If the movie is in memory, the returned offset reflects the location the data will have in the movie on a permanent storage device.

sgOut

A pointer to the sequence grabber output to which the data was written.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function differs from SGWriteMovieData, in two respects: the offset parameter has a 64-bit value, and the sgOut parameter does not exist in SGWriteMovieData.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGWriteMovieData

Lets a channel component add data to a movie.

ComponentResult SGWriteMovieData (
   SeqGrabComponent s,
   SGChannel c,
   Ptr p,
   long len,
   long *offset
);

Parameters
s

An instance of the sequence grabber component connected to your channel component. The sequence grabber component provides this value through SGInitChannel.

c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

p

The location of the data to be added to the movie.

len

The number of bytes of data to be added to the movie.

offset

A pointer to a long integer that is to receive the offset to the new data in the movie. The sequence grabber component returns an offset that is correct in the context of a movie resource, even if the movie data is currently stored in memory. That is, if the movie is in memory, the returned offset reflects the location that the data will have in a movie on a permanent storage device, such as a disk.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

SGWriteSamples

Called by a sequence grabber component when it is ready to add recorded data to a movie.

ComponentResult SGWriteSamples (
   SGChannel c,
   Movie m,
   AliasHandle theFile
);

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

m

Identifies the movie to which your component should add the captured data. Your component should not make any other changes to the movie identified by this reference. Use SGWriteMovieData instead.

theFile

Identifies the movie file. The sequence grabber component provides this alias so that you can supply it to the Movie Toolbox. You should not open this file or write to it directly. Use SGWriteMovieData instead.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

Callbacks

SGAddFrameBottleProc

Undocumented

typedef ComponentResult (*SGAddFrameBottleProcPtr) (SGChannel c, short bufferNum, TimeValue atTime, TimeScale scale, const SGCompressInfo *ci,
long refCon);

If you name your function MySGAddFrameBottleProc, you would declare it this way:

ComponentResult MySGAddFrameBottleProc (
   SGChannel               c,
   short                   bufferNum,
   TimeValue               atTime,
   TimeScale               scale,
   const SGCompressInfo    *ci,
   long                    refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

atTime

Undocumented

scale

The current time scale.

ci

A pointer to a SGCompressInfo structure.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGCompressBottleProc

Undocumented

typedef ComponentResult (*SGCompressBottleProcPtr) (SGChannel c, short bufferNum, long refCon);

If you name your function MySGCompressBottleProc, you would declare it this way:

ComponentResult MySGCompressBottleProc (
   SGChannel    c,
   short        bufferNum,
   long         refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGCompressCompleteBottleProc

Undocumented

typedef ComponentResult (*SGCompressCompleteBottleProcPtr) (SGChannel c, short bufferNum, Boolean *done, SGCompressInfo *ci, long refCon);

If you name your function MySGCompressCompleteBottleProc, you would declare it this way:

ComponentResult MySGCompressCompleteBottleProc (
   SGChannel         c,
   short             bufferNum,
   Boolean           *done,
   SGCompressInfo    *ci,
   long              refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

done

A pointer to a Boolean; return TRUE if the task was completed, FALSE otherwise.

ci

A pointer to a SGCompressInfo structure.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGDataProc

Undocumented

typedef OSErr (*SGDataProcPtr) (SGChannel c, Ptr p, long len, long *offset, long chRefCon, TimeValue time, short writeType, long refCon);

If you name your function MySGDataProc, you would declare it this way:

OSErr MySGDataProc (
   SGChannel    c,
   Ptr          p,
   long         len,
   long         *offset,
   long         chRefCon,
   TimeValue    time,
   short        writeType,
   long         refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

p

Undocumented

len

Undocumented

offset

Undocumented

chRefCon

Undocumented

time

Undocumented

writeType

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGDisplayBottleProc

Undocumented

typedef ComponentResult (*SGDisplayBottleProcPtr) (SGChannel c, short bufferNum, MatrixRecord *mp, RgnHandle clipRgn, long refCon);

If you name your function MySGDisplayBottleProc, you would declare it this way:

ComponentResult MySGDisplayBottleProc (
   SGChannel       c,
   short           bufferNum,
   MatrixRecord    *mp,
   RgnHandle       clipRgn,
   long            refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

mp

Undocumented

clipRgn

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGDisplayCompressBottleProc

Undocumented

typedef ComponentResult (*SGDisplayCompressBottleProcPtr) (SGChannel c, Ptr dataPtr, ImageDescriptionHandle desc, MatrixRecord *mp, RgnHandle clipRgn,
long refCon);

If you name your function MySGDisplayCompressBottleProc, you would declare it this way:

ComponentResult MySGDisplayCompressBottleProc (
   SGChannel                 c,
   Ptr                       dataPtr,
   ImageDescriptionHandle    desc,
   MatrixRecord              *mp,
   RgnHandle                 clipRgn,
   long                      refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

dataPtr

Undocumented

desc

Undocumented

mp

Undocumented

clipRgn

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGGrabBottleProc

Undocumented

typedef ComponentResult (*SGGrabBottleProcPtr) (SGChannel c, short bufferNum, long refCon);

If you name your function MySGGrabBottleProc, you would declare it this way:

ComponentResult MySGGrabBottleProc (
   SGChannel    c,
   short        bufferNum,
   long         refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGGrabCompleteBottleProc

Undocumented

typedef ComponentResult (*SGGrabCompleteBottleProcPtr) (SGChannel c, short bufferNum, Boolean *done, long refCon);

If you name your function MySGGrabCompleteBottleProc, you would declare it this way:

ComponentResult MySGGrabCompleteBottleProc (
   SGChannel    c,
   short        bufferNum,
   Boolean      *done,
   long         refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

done

A pointer to a Boolean; return TRUE if the task was completed, FALSE otherwise.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGGrabCompressCompleteBottleProc

Undocumented

typedef ComponentResult (*SGGrabCompressCompleteBottleProcPtr) (SGChannel c, Boolean *done, SGCompressInfo *ci, TimeRecord *t, long refCon);

If you name your function MySGGrabCompressCompleteBottleProc, you would declare it this way:

ComponentResult MySGGrabCompressCompleteBottleProc (
   SGChannel         c,
   UInt8             *queuedFrameCount,
   SGCompressInfo    *ci,
   TimeRecord        *t,
   long              refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

queuedFrameCount

A pointer to the number of queued frames yet to be done. 0 means no frames. Some VDIGs may return 2 even if more than 2 frames are available, and some will return 1 if any number more than 0 are available.

ci

A pointer to a SGCompressInfo structure. When the compression operation is complete, this structure is filled with information about it.

t

A pointer to a TimeRecord structure. When the compression operation is complete, this structure is used to indicate what time the frame was grabbed.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

SGModalFilterProc

Undocumented

typedef Boolean (*SGModalFilterProcPtr) (DialogPtr theDialog, const EventRecord *theEvent, short *itemHit, long refCon);

If you name your function MySGModalFilterProc, you would declare it this way:

Boolean MySGModalFilterProc (
   DialogPtr            theDialog,
   const EventRecord    *theEvent,
   short                *itemHit,
   long                 refCon );

Parameters
theDialog

A pointer to a dialog box.

theEvent

Undocumented

itemHit

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

Return TRUE if the event was handled, FALSE otherwise.

Declared In
QuickTimeComponents.h

SGTransferFrameBottleProc

Undocumented

typedef ComponentResult (*SGTransferFrameBottleProcPtr) (SGChannel c, short bufferNum, MatrixRecord *mp, RgnHandle clipRgn, long refCon);

If you name your function MySGTransferFrameBottleProc, you would declare it this way:

ComponentResult MySGTransferFrameBottleProc (
   SGChannel       c,
   short           bufferNum,
   MatrixRecord    *mp,
   RgnHandle       clipRgn,
   long            refCon );

Parameters
c

The connection identifier for the channel for this operation. You get this value from SGNewChannel or SGNewChannelFromComponent.

bufferNum

A buffer identifier provided by the sequence grabber component.

mp

Undocumented

clipRgn

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeComponents.h

Data Types

ConstComponentListPtr

Represents a type used by the Sequence Grabber API.

typedef const Component * ConstComponentListPtr;

Availability
Declared In
QuickTimeComponents.h

SeqGrabComponent

Represents a type used by the Sequence Grabber API.

typedef ComponentInstance SeqGrabComponent;

Availability
Declared In
QuickTimeComponents.h

SeqGrabExtendedFrameInfo

Defines a frame for a sequence grabber component and its sequence grabber channel components.

struct SeqGrabExtendedFrameInfo {
   wide         frameOffset;
   long         frameTime;
   long         frameSize;
   SGChannel    frameChannel;
   long         frameRefCon;
   SGOutput     frameOutput;
};

Fields
frameOffset
Discussion

Specifies the offset to the sample. Note that this is a 64-bit value.

frameTime
Discussion

Specifies the time at which the frame was captured by a sequence grabber channel component. The time value is relative to the data sequence. The channel component must choose a time scale and use it consistently for all sample references.

frameSize
Discussion

Specifies the number of bytes in the current sample.

frameChannel
Discussion

Identifies the current connection to the channel component.

frameRefCon
Discussion

Contains a reference constant for use by the channel component. The channel component uses this constant in any appropriate way; for example, to store a reference to frame differencing information for a time-compressed sequence.

frameOutput
Discussion

Identifies the sequence grabber output used to store captured data referenced by the current record.

Discussion

This structure differs from SeqGrabFrameInfo in two respects: the frameOffset field takes a 64-bit value, and the frameOutput field does not exist in SeqGrabFrameInfo.

Version Notes

Introduced in QuickTime 4.

Related Functions
SGAddExtendedFrameReference
SGGetNextExtendedFrameReference
Declared In
QuickTimeComponents.h

SeqGrabExtendedFrameInfoPtr

Represents a type used by the Sequence Grabber API.

typedef SeqGrabExtendedFrameInfo * SeqGrabExtendedFrameInfoPtr;

Availability
Declared In
QuickTimeComponents.h

SeqGrabFrameInfo

Provides information about a frame for a sequence grabber component and its sequence grabber channel components.

struct SeqGrabFrameInfo {
   long         frameOffset;
   long         frameTime;
   long         frameSize;
   SGChannel    frameChannel;
   long         frameRefCon;
};

Fields
frameOffset
Discussion

Specifies the offset to the sample. Your channel component obtains this value from SGWriteMovieData.

frameTime
Discussion

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
Discussion

Specifies the number of bytes in the sample described by the sample reference.

frameChannel
Discussion

Identifies the current connection to your channel.

frameRefCon
Discussion

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.

Discussion

This structure differs from SeqGrabExtendedFrameInfo in two respects: the frameOffset field takes a 32-bit value, and SeqGrabExtendedFrameInfo has a frameOutput field.

Related Functions
SGAddFrameReference
SGGetNextFrameReference
Declared In
QuickTimeComponents.h

SeqGrabFrameInfoPtr

Represents a type used by the Sequence Grabber API.

typedef SeqGrabFrameInfo * SeqGrabFrameInfoPtr;

Availability
Declared In
QuickTimeComponents.h

SGAddFrameBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGAddFrameBottleProcPtr) SGAddFrameBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGChannel

Represents a type used by the Sequence Grabber API.

typedef ComponentInstance SGChannel;

Availability
Declared In
QuickTimeComponents.h

SGCompressBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGCompressBottleProcPtr) SGCompressBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGCompressCompleteBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGCompressCompleteBottleProcPtr) SGCompressCompleteBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGCompressInfo

Defines the characteristics of a buffer that contains a captured image that has been compressed.

struct SGCompressInfo {
   Ptr              buffer;
   unsigned long    bufferSize;
   UInt8            similarity;
   UInt8            reserved;
};

Fields
buffer
Discussion

Points to the buffer that contains the compressed image. This pointer must contain a 32-bit clean address.

bufferSize
Discussion

Specifies the number of bytes of image data in the buffer.

similarity
Discussion

Indicates the relative similarity of this image to the previous image in a sequence. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254).

reserved
Discussion

Reserved; set to 0.

Discussion

Callback functions use this structure to exchange information about compressed images. For example, SGCompressCompleteBottleProc must format a compression information record whenever a video frame is compressed.

Related Functions
SGCompressCompleteBottleProc
SGCompressFrameComplete
SGGrabCompressComplete
SGGrabCompressCompleteBottleProc
Declared In
QuickTimeComponents.h

SGDataUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGDataProcPtr) SGDataUPP;

Availability
Declared In
QuickTimeComponents.h

SGDeviceList

Represents a type used by the Sequence Grabber API.

typedef SGDeviceListPtr * SGDeviceList;

Availability
Declared In
QuickTimeComponents.h

SGDeviceListPtr

Represents a type used by the Sequence Grabber API.

typedef SGDeviceListRecord * SGDeviceListPtr;

Availability
Declared In
QuickTimeComponents.h

SGDisplayBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGDisplayBottleProcPtr) SGDisplayBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGDisplayCompressBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGDisplayCompressBottleProcPtr) SGDisplayCompressBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGGrabBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGGrabBottleProcPtr) SGGrabBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGGrabCompleteBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGGrabCompleteBottleProcPtr) SGGrabCompleteBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGGrabCompressCompleteBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGGrabCompressCompleteBottleProcPtr) SGGrabCompressCompleteBottleUPP;

Availability
Declared In
QuickTimeComponents.h

SGModalFilterUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGModalFilterProcPtr) SGModalFilterUPP;

Availability
Declared In
QuickTimeComponents.h

SGOutput

Represents a type used by the Sequence Grabber API.

typedef SGOutputRecord * SGOutput;

Availability
Declared In
QuickTimeComponents.h

SGOutputRecord

Contains a sequence grabber output.

struct SGOutputRecord {
   long    data[1];
};

Fields
data
Discussion

An array of data.

Declared In
QuickTimeComponents.h

SGTransferFrameBottleUPP

Represents a type used by the Sequence Grabber API.

typedef STACK_UPP_TYPE(SGTransferFrameBottleProcPtr) SGTransferFrameBottleUPP;

Availability
Declared In
QuickTimeComponents.h

VideoBottles

Identifies the callback functions to be assigned to a sequence grabber channel.

struct VideoBottles {
   short                              procCount;
   SGGrabBottleUPP                    grabProc;
   SGGrabCompleteBottleUPP            grabCompleteProc;
   SGDisplayBottleUPP                 displayProc;
   SGCompressBottleUPP                compressProc;
   SGCompressCompleteBottleUPP        compressCompleteProc;
   SGAddFrameBottleUPP                addFrameProc;
   SGTransferFrameBottleUPP           transferFrameProc;
   SGGrabCompressCompleteBottleUPP    grabCompressCompleteProc;
   SGDisplayCompressBottleUPP         displayCompressProc;
};

Fields
procCount
Discussion

Specifies the number of callback functions that may be identified in the structure. Set this field to 9.

grabProc
Discussion

Identifies the SGGrabBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

grabCompleteProc
Discussion

Identifies the SGGrabCompleteBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

displayProc
Discussion

Identifies the SGDisplayBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

compressProc
Discussion

Identifies the SGCompressBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

compressCompleteProc
Discussion

Identifies the SGCompressCompleteBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

addFrameProc
Discussion

Identifies the SGAddFrameBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

transferFrameProc
Discussion

Identifies the SGTransferFrameBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

grabCompressCompleteProc
Discussion

Identifies the SGGrabCompressCompleteBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

displayCompressProc
Discussion

Identifies the SGDisplayCompressBottleProc function. If you are setting such a function, set this field so that it points to the function's entry point. If you are not setting such a function, set this field to NIL.

Related Functions
SGGetVideoBottlenecks
SGSetVideoBottlenecks
Declared In
QuickTimeComponents.h

Constants

channelPlayAllData

Constants grouped with channelPlayAllData.

enum {
   /*
   * Play flag specifying that the SGChannel should use its default
   * preview/playthru methodology.  Currently it is only used by the
   * VideoMediaType SGChannel.
   */
   channelPlayNormal             = 0,
   /*
   * Play flag specifying that the SGChannel should sacrifice playback
   * quality to achieve the specified playback rate.  Currently it is
   * only used by the VideoMediaType SGChannel.
   */
   channelPlayFast               = 1L << 0,
   /*
   * Play flag specifying that the SGChannel should play its data at
   * the highest possible quality. This option sacrifices playback rate
   * for the sake of image quality. It may reduce the amount of
   * processor time available to other programs in the computer. This
   * option should not affect the quality of the recorded data,
   * however.  Currently it is only used by the VideoMediaType
   * SGChannel.
   */
   channelPlayHighQuality        = 1L << 1,
   /*
   * Play flag specifying that the SGChannel should try to play all of
   * the data it captures,
   even the data that is stored in offscreen
   * buffers. This option is useful when you want to be sure that the
   * user sees as much of the captured data as possible. The sequence
   * grabber component sets this flag to 1 to play all the captured
   * data. The sequence grabber component may combine this flag with
   * any of the other values for the playFlags parameter.  Currently it
   * is only used by the VideoMediaType SGChannel.
   */
   channelPlayAllData            = 1L << 2,
   /*
   * Play flag specifying that the SGChannel should preview/play raw
   * audio samples just after they are captured from its recording
   * device.  Currently it is only used by the SGAudioMediaType
   * SGChannel.
   */
   channelPlayPreMix             = 1L << 3,
   /*
   * Play flag specifying that the SGChannel should preview/play audio
   * samples just after they are mixed down to the client-specified
   * movie track channel layout.  Currently it is only used by the
   * SGAudioMediaType SGChannel.
   */
   channelPlayPostMix            = 1L << 4,
   /*
   * Play flag specifying that the SGChannel should preview/play audio
   * samples just before they are interleaved/converted/compressed to
   * the client-specified movie track format.  Currently it is only
   * used by the SGAudioMediaType SGChannel.
   */
   channelPlayPreConversion      = 1L << 5,
   /*
   * Play flag specifying that the SGChannel should preview/play audio
   * samples after they have been interleaved/converted/compressed to
   * the client-specified movie track format.  Currently it is only
   * used by the SGAudioMediaType SGChannel.
   */
   channelPlayPostConversion     = 1L << 6
};

Declared In
QuickTimeComponents.h

SGGrabPict Values

Constants passed to SGGrabPict.

enum {
   grabPictOffScreen             = 1,
   grabPictIgnoreClip            = 2,
   grabPictCurrentImage          = 4
};

Declared In
QuickTimeComponents.h

seqGrabCanMoveWindowWhileRecording

Constants grouped with seqGrabCanMoveWindowWhileRecording.

enum {
   seqGrabHasBounds              = 1,
   seqGrabHasVolume              = 2,
   seqGrabHasDiscreteSamples     = 4,
   seqGrabDoNotBufferizeData     = 8,
   seqGrabCanMoveWindowWhileRecording = 16
};

Declared In
QuickTimeComponents.h

seqGrabAlwaysUseTimeBase

Constants grouped with seqGrabAlwaysUseTimeBase.

enum {
   seqGrabRecord                 = 1,
   seqGrabPreview                = 2,
   seqGrabPlayDuringRecord       = 4,
   seqGrabLowLatencyCapture      = 8,    /* return the freshest frame possible,
   for live work (videoconferencing,
   live broadcast,
   live image processing) */
   seqGrabAlwaysUseTimeBase      = 16,   /* Tell VDIGs to use TimebaseTime always,
   rather than creating uniform frame durations,
   for more accurate live sync with audio */
   seqGrabRecordPreferQualityOverFrameRate = 32 /* quality is more important than frame rate: client rather drop frame instead of lower quality to achieve full frame rate */
};

Declared In
QuickTimeComponents.h

SGSettingsDialog Values

Constants passed to SGSettingsDialog.

enum {
   seqGrabSettingsPreviewOnly    = 1
};

Declared In
QuickTimeComponents.h

seqGrabAppendToFile

Constants grouped with seqGrabAppendToFile.

enum {
   seqGrabToDisk                 = 1,
   seqGrabToMemory               = 2,
   seqGrabDontUseTempMemory      = 4,
   seqGrabAppendToFile           = 8,
   seqGrabDontAddMovieResource   = 16,
   seqGrabDontMakeMovie          = 32,
   seqGrabPreExtendFile          = 64,
   seqGrabDataProcIsInterruptSafe = 128,
   seqGrabDataProcDoesOverlappingReads = 256,
   seqGrabDontPreAllocateFileSize = 512  /* Don't set the size of the file before capture unless the file has been pre-extended */
};

Declared In
QuickTimeComponents.h

SGGetPause Values

Constants passed to SGGetPause.

enum {
   seqGrabUnpause                = 0,
   seqGrabPause                  = 1,
   seqGrabPauseForMenu           = 3
};

Declared In
QuickTimeComponents.h

SGAddMovieData Values

Constants passed to SGAddMovieData.

enum {
   seqGrabWriteAppend            = 0,
   seqGrabWriteReserve           = 1,
   seqGrabWriteFill              = 2
};

Declared In
QuickTimeComponents.h

SGGetChannelDeviceList Values

Constants passed to SGGetChannelDeviceList.

enum {
   sgDeviceListWithIcons         = (1 << 0),
   sgDeviceListDontCheckAvailability = (1 << 1),
   sgDeviceListIncludeInputs     = (1 << 2)
};

Declared In
QuickTimeComponents.h

sgFlagAllowNonRGBPixMaps

Constants grouped with sgFlagAllowNonRGBPixMaps.

enum {
   sgFlagControlledGrab          = (1 << 0),
   sgFlagAllowNonRGBPixMaps      = (1 << 1)
};

Declared In
QuickTimeComponents.h

SGSetChannelSettingsStateChanging Values

Constants passed to SGSetChannelSettingsStateChanging.

enum {
   sgSetSettingsBegin            = (1 << 0), /* SGSetSettings related set calls about to start*/
   sgSetSettingsEnd              = (1 << 1) /* Finished SGSetSettings calls. Get ready to use the new settings*/
};

Declared In
QuickTimeComponents.h

Next Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.