Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Types

The SGDeviceInputName structure is defined as follows:

This section describes each new structure that is available in QuickTime 6.

struct SGDeviceInputName {

   Str63                           name;

   Handle                          icon;

   long                            flags;

   long                            reserved; /* zero*/

};

typedef struct SGDeviceInputName SGDeviceInputName;

enum {

   sgDeviceInputNameFlagInputUnavailable = (1 << 0)

};

struct SGDeviceInputListRecord {

   short                           count;

   short                           selectedIndex;

   long                            reserved; /* zero*/

   SGDeviceInputName               entry[1];

};

typedef struct SGDeviceInputListRecord  SGDeviceInputListRecord;

typedef SGDeviceInputListRecord *       SGDeviceInputListPtr;

typedef SGDeviceInputListPtr *          SGDeviceInputList;

The SGDeviceName structure is re-defined as follows:

struct SGDeviceName {

   Str63                           name;

   Handle                          icon;

   long                            flags;

   long                            refCon;

   SGDeviceInputList               inputs; /* list of inputs; formerly

                                            reserved to 0*/

};

typedef struct SGDeviceName SGDeviceName;

enum {

   sgDeviceNameFlagDeviceUnavailable = (1 << 0),

   sgDeviceNameFlagShowInputsAsDevices = (1 << 1)

};

The SGDeviceListRecord structure is defined as follows:

struct SGDeviceListRecord {

   short                           count;

   short                           selectedIndex;

   long                            reserved; /* zero*/

   SGDeviceName                    entry[1];

};

typedef struct SGDeviceListRecord       SGDeviceListRecord;

typedef SGDeviceListRecord *            SGDeviceListPtr;

typedef SGDeviceListPtr *               SGDeviceList;

enum {

   sgDeviceListWithIcons       = (1 << 0),

   sgDeviceListDontCheckAvailability = (1 << 1),

   sgDeviceListIncludeInputs   = (1 << 2)

};

The new flag sgDeviceListIncludeInputs is passed to SGGetChannelDeviceList if the caller desires to get the list of inputs as well as the devices. If this flag is not passed, the old behavior of just listing devices is retained.

Two new usage flags have also been defined so that your application can indicate to the sequence grabber (and thus the VDIG) that it is not being used in a conventional recording mode.

enum {

    seqGrabRecord               = 1,

    seqGrabPreview              = 2,

    seqGrabPlayDuringRecord     = 4,

    seqGrabLowLatencyCapture    = 8, /* return the freshest frame

                                        possible, for live work

                                        (i.e. 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 */

};

typedef unsigned long SeqGrabUsageEnum;

SGSetSettingsSummary

Sets what is displayed in the lower left corner of the sequence grabber dialog.

SGSetSettingsSummary (SeqGrabComponent s,
Handle summaryText);

Parameters

s

A sequence grabber component.

summaryText

A handle to the summary text.

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.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

SGGetChannelRefCon

Returns a reference constant that was previously set by the corresponding set call.

SGGetChannelRefCon (SGChannel c,
   long * refCon);

Parameters

c

A sequence grabber channel.

refCon

A pointer to a long integer.

Discussion

This routine returns the application reference constant set with SGSetChannelRefCon. Previously, this was only passed to the BottleProcs.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

SGGetChannelDeviceAndInputNames

Returns the current device and input names.

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

Parameters

c

A sequence grabber channel.

outDeviceName

The names for display.

outInputName

The input name for display.

outInputNumber

A pointer to the number of currently selected inputs.

Discussion

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

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

SGSetChannelDeviceInputNames

A media format independent call for this. Inputs start at 0 here. (Sound starts at 1, VDIGs at 0 in direct calls.) Previously, you had to make a VDIG or SoundDevice call in order to accomplish this.

ComponentResult SGSetChannelDeviceInputNames (
SGChannel c
short inInputNumber);

Parameters

c

A sequence grabber channel.

inInputNumber

An error specifying if it works or not.

Introduced in QuickTime 6.

C interface file: QuickTimeComponents.h

SGSetChannelSettingsStateChanging

This is a call to bracket SetSettings-related calls, and to give downstream components an opportunity to deal with the entire settings change in one go. An application should not normally need to call this because the sequence grabber settings calls will do this.

ComponentResult SGSetChannelSettingsStateChanging(
SGChannel c,
UInt32 inFlags);

Parameters

c

A sequence grabber channel.

inFlags

See below.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

enum

{

    sgSetSettingsBegin = (1<<0), // SGSetSettings related

                                // set calls about to start

    sgSetSettingsEnd = (1<<1), // Finished SGSetSettings

                                // calls. Get ready to use the new

                                // settings

};

Introduced in QuickTime 6.

C interface file: QuickTimeComponents.h

SGPanelGetDITLForSize

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

SGPanelGetDITLForSize (SeqGrabComponent ci,
   Handle * ditl,
   Point * requestedSize);

Parameters

ci

A component instance.

ditl

A pointer to a handle provided by the sequence grabber component.

requestedSize

The size requested.

Discussion

This routine is used to retrieve user interface elements that fit within a specified size panel.

If SGPanelGetDITLForSize is unimplemented entirely, the panel is assumed to not have resizable User Interface elements.

The sequence grabber will interpolate the panel elements between these two sizes if just these are returned.

enum {

   kSGSmallestDITLSize = -1, /* requestedSize h and v set to this to

                                retrieve small size*/

   kSGLargestDITLSize = -2 /* requestedSize h and v set to this to

                                retrieve large size*/

};

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

SGGrabCompressCompleteBottleProcPtr

Note that UInt8 *queuedFrameCount replaces Boolean *done. (0 (==false) still means no frames, and 1 (==true) one, but if more than one are available, the number should be returned here.

ComponentResult (*SGGrabCompressCompleteBottleProcPtr)
(SGChannel c,
UInt8 *queuedFrameCount,
SGCompressInfo *ci,
TimeRecord *t,
long refCon);

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 an 8-bit frame count identifier.

ci

A pointer to a SGCompressInfo (IV–2488) structure. When the operation is complete, the function fills in this structure with information about the compression operation.

t

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

refCon

A reference constant.

The value 2 previously meant more than one frame, so some VDIGs may return 2 even if more than 2 are available, and some will still return 1 as they are using the original definition.

Introduced in QuickTime 6.

C interface file: QuickTimeComponents.h

SGGrabCompressComplete

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

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 an 8-bit frame count identifier.

ci

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

tr

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

Return Value

See “Error Codes” (IV–2718). Returns noErr if there is no error.

Discussion

Note that UInt8 * queuedFrameCount replaces Boolean *done. 0 (==false) still means no frames, and 1 (==true) one, but if more than one are available the number should be returned here. The value 2 previously meant more than one frame, so some VDIGs may return 2 even if more than 2 are available, and some will still return 1 as they are using the original definition.

The SGGrabCompressCompleteBottleProc definition has also changed accordingly. By setting this BottleProc, and calling through to SGGrabCompressComplete, your application can determine how many frames are currently queued in the VDIG, which can be useful for real-time processing. Similarly, the VDCompressDone call has been re-defined. VDIG writers should update to this new model.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

C interface file: QuickTimeComponents.h

VDCompressDone

Determines whether the video digitizer has finished digitizing and compressing a frame of image data.

VDCompressDone (VideoDigitizerComponent  ci,
   UInt8 * queuedFrameCount,
   Ptr * theData,
   long * dataSize,
   UInt8 * similarity,
   TimeRecord * t);

Parameters

ci

The component instance that identifies your connection to the video digitizer component. An application obtains this value from OpenComponent (II–1161) or OpenDefaultComponent (II–1163).

queuedFrameCount

A pointer to an 8-bit frame count identifier.

theData

A pointer to a field that is to receive a pointer to the compressed image data. The digitizer returns a pointer that is valid in the application’s current memory mode.

dataSize

A pointer to a field to receive a value indicating the number of bytes of compressed image data.

similarity

A pointer to a field to receive an indication of 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). This field is only filled in if the temporal quality passed in with VDSetCompression (III–2090) is not 0; that is, if it is not frame-differenced.

t

A pointer to a TimeRecord (IV–2542) structure. When the operation is complete, the digitizer fills in this structure with information indicating when the frame was grabbed. The time value stored in this structure is in the time base that the application sets with VDSetTimeBase (III–2111).

Return Value

See “Error Codes” (IV–2718). Returns noErr if there is no error.

Discussion

Note that UInt8 * queuedFrameCount replaces Boolean* done. 0 (==false) still means no frames, and 1 (==true) one, but if more than one are available the number should be returned here. The value 2 previously meant more than one frame, so some VDIGs may return 2 even if more than 2 are available, and some will still return 1 as they are using the original definition.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

C interface file: QuickTimeComponents.h

VDGetDeviceNameAndFlags

Returns the name of the input device.

VDGetDeviceNameAndFlags (VideoDigitizerComponent ci,
   Str255 outName,
   UInt32 * outNameFlags);

Parameters

ci

The component instance that identifies your connection to the video digitizer component. An application obtains this value from OpenComponent (II–1161) or OpenDefaultComponent (II–1163).

outName

The name of the display name.

outNameFlags

A pointer to flags (see below)

Discussion

This routine is designed to give the VDIG more control over how it is presented to the user, and to clarify the distinction between devices and inputs. Historically, the assumption has been that there is one component registered per device and the component name is displayed. This change lets a component choose its name after registration. vdDeviceFlagShowInputsAsDevices is meant for components that register once and support multiple devices.

The User Interface is clearer if these are presented as devices rather than inputs, and this allows a VDIG to present itself this way without a huge restructuring. vdDeviceFlagHideDevice is for the kind of VDIG that registers itself, and then can register a further VDIG for each device.

If no hardware is available, returning this flag will omit it from the list.

As this call is being made, it is also a good time to check for hardware and register further VDIG components if needed, allowing for lazy initialization when the application needs to find a VDIG rather than on every launch or replug.

enum {

   vdDeviceFlagShowInputsAsDevices = (1 << 0), /* Tell the Panel to

                                            promote Inputs to Devices*/

   vdDeviceFlagHideDevice = (1 << 1) /* Omit this Device enitirely from

                                        the list*/

};

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

VDCaptureStateChanging

Returns a component error.

VDCaptureStateChanging (VideoDigitizerComponent ci,
   UInt32 inStateFlags);

Parameters

ci

The component instance that identifies your connection to the video digitizer component.

inStateFlags

See below.

Discussion

It has long been a problem for VDIG writers that the sequence grabber can make a series of calls, and it is not always clear what the intent is at the higher level. This call is designed to provide additional information about what is happening at the sequence grabber level to the VDIG, so it can take this into account. In particular, the settings bracketing calls are designed for the VDIG to update a series of parameters without re-initializing. One point here is that the VDIG can consider the UniqueID call to be more important than the input number, for example.

The sequence grabber is now more careful when there are multiple VDIGs available to try to save and restore more information about which one should be used. It will still pick the closest available VDIG if the exact one is not available, but it will not stop with the first available.

In addition, the old behavior of aborting a Get/Set settings call part of the way through if an error is returned has been changed to leave the sequence grabber in a more predictable state. It also no longer tries to save or restore settings for SGPanels that report that their hardware is unavailable.

enum {

   vdFlagCaptureStarting = (1 << 0), // Capture is about to start;

                                        allocate bandwidth

   vdFlagCaptureStopping = (1 << 1), // Capture is about to stop; stop

                                        queuing frames

   vdFlagCaptureIsForPreview = (1 << 2),// Capture is just to screen for

                                         preview purposes

   vdFlagCaptureIsForRecord = (1 << 3) // Capture is going to be

                                         recorded

    vdFlagCaptureStarting = (1<<0), // Capture is about to start;

                                        allocate bandwidth

    vdFlagCaptureStopping = (1<<1), // Capture is about to stop;

                                        stop queuing frames

    vdFlagCaptureIsForPreview = (1<<2), // Capture is just to

                                        screen for preview purposes

    vdFlagCaptureIsForRecord = (1<<3), // Capture is going to be recorded

    vdFlagCaptureLowLatency = (1<<4), // Fresh frames are more important

                                        than delivering every frame --

                                        don't queue too much

    vdFlagCaptureAlwaysUseTimeBase = (1<<5),// Use the timebase

                                        for every frame;

                                        don't worry about making

                                        durations uniform

    vdFlagCaptureSetSettingsBegin = (1<<6), // A series of calls

                                        are about to be made to

                                        restore settings

    vdFlagCaptureSetSettingsEnd = (1<<7) // Finished restoring settings;

                                            any set calls after this

                                            are from the app or UI

};

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

VDGetUniqueIDs

Returns a unique identifier for a particular device, which, in the case of a FireWire device, is the FireWire ID.

VDGetUniqueIDs (VideoDigitizerComponent ci,
   UInt64 * outDeviceID,
   UInt64 * outInputID);

Parameters

ci

The component instance that identifies your connection to the video digitizer component.

outDeviceID

A pointer to a 64-bit hardware identifier.

outInputID

A pointer to a 64-bit hardware identifier.

Discussion

These UniqueID calls are provided, so that the VDIG can give the sequence grabber information, enabling it to restore a particular configuration, i.e., choose a particular device and input from those available––for example, if you need to restore a specific camera for a set of several hot-plugged FireWire cameras. The caller can pass NIL if it is not interested in one of the IDs. Returning 0 in an ID means you don’t have one.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

VDSelectUniqueIDs

Selects a particular device––for example, the IDs from the previous call.

VDSelectUniqueIDs (VideoDigitizerComponent ci,
const UInt64 * inDeviceID,
const UInt64 * inInputID);

Parameters

ci

The component instance that identifies your connection to the video digitizer component.

inDeviceID

A pointer to 64-bit hardware identifier.

inInputID

A pointer to 64-bit hardware identifier.

Discussion

Note this is a Select, not a Set. The assumption is that the Unique ID is a function of the hardware and not modifiable by the calling application. Either a NIL pointer or 0 in the ID means, don’t care. This should restore the device and input IDs returned by VDGetUniqueIDs.

return vdDontHaveThatUniqueIDErr if your device doesn’t have a match.

Introduced in QuickTime 6.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

C interface file: QuickTimeComponents.h

< Previous PageNext Page > Hide TOC

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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice