Spatial Settings Request Type

Use the spatial settings request to retrieve or modify the current spatial compression parameters. These parameters control how each image is compressed.

You supply a pointer to a spatial settings structure. If you are retrieving these settings, the standard dialog component places the current settings into the specified structure; if you are changing the settings, place the new values into the structure. The component uses those values to update its settings.

The SCSpatialSettings data type defines the format and content of the spatial settings structure:

typedef struct {

    CodecType           codecType;         /* compressor type */

    CodecComponent      codec;             /* compressor */

    short               depth;             /* pixel depth */ 

    CodecQ              spatialQuality;    /* desired quality */

} SCSpatialSettings;

The scListEveryCodec bit in the flag in the scPreferenceFlagsType request influences the operation of the compressor list in the dialog box and, therefore, the way the component uses the codec field. Set the flag to 1 to have the list contain an entry for each compressor component in the system. If the flag is set to 1, the standard image compression dialog component uses this field along with the codecType field to select the default compressor that appears in the dialog box. To specify a default image compressor component, set this field to the appropriate compressor identifier. When the user clicks OK in the dialog box, the standard image compression dialog component returns the compressor identifier that corresponds to the selected image compressor component.

If you set the codec field to nil, the standard image compression dialog component uses as the default value the first compressor of the specified type that it retrieves from the Image Compression Manager. If you have set the flag to 0, the list contains only one entry for each type of compressor in the system. The standard image compression dialog component ignores this field when creating the list of compressor types. In this case, the standard image compression dialog component does not change the value of this field when the user clicks OK.

However, you may use the codec field to specify additional selection criteria by setting this field to one of the special compressor identifiers supported by the Image Compression Manager. The standard image compression dialog component may use this value when it validates the compression parameters selected by the user.

Temporal Settings Request Type

Use the temporal settings request to retrieve or modify the current temporal compression parameters. These parameters govern sequence-compression operations.

You supply a pointer to a temporal settings structure. If you are retrieving these settings, the standard dialog component places the current settings into the specified structure; if you are changing the settings, place the new values into the structure. The component uses those values to update its settings.

The SCTemporalSettings data type defines the format and content of the temporal settings structure:

typedef struct {

    CodecQ      temporalQuality;    /* desired quality */

    Fixed       frameRate;          /* frame rate */

    long        keyFrameRate;       /* key frame rate */

} SCTemporalSettings;

Data-Rate Settings Request Type

Use the data-rate settings request to retrieve or modify the current temporal compression parameters that govern the data rate. These parameters affect sequence-compression operations.

You supply a pointer to a data-rate settings structure. If you are retrieving these settings, the standard dialog component places the current settings into the specified structure; if you are changing the settings, place the new values into the structure; the component uses those values to update its settings.

The SCDataRateSettings data type defines the format and content of the data-rate settings structure:

typedef struct {

    long        dataRate;              /* desired data rate */

    long        frameDuration;         /* frame duration */

    CodecQ      minSpatialQuality;     /* minimum value */

    CodecQ      minTemporalQuality;    /* minimum value */

} SCDataRateSettings;

Color Table Settings Request Type

Use the color table settings request to retrieve or modify the color table that the standard dialog component uses with all compression operations. Unless you specify otherwise, the component extracts the color table from the source image or sequence.

You supply a pointer to a color table handle (CTabHandle data type). Your application is responsible for disposing of this handle when you are done with it. Set the pointer to nil to clear the current color table; this may be useful if the current color table is inappropriate for the image or sequence you are working with.

Progress Function Request Type

Use the progress function request to assign a progress function for use by the standard dialog component. The progress function is a part of your application. The standard dialog component calls this function during time-consuming operations, and reports its progress. Your progress function can use the information it receives from the standard dialog component to keep the user informed about the progress of the operation.

You supply a pointer to an Image Compression Manager progress function structure. Set the pointer to nil to clear the current progress function; in this case, the standard dialog component does not report its progress to the user. Set the pointer to -1 to use the component’s default progress function.

Extended Functions Request Type

Use the extended functions request to extend the interface provided in the standard image or sequence dialog boxes. You may specify a filter function, a hook function, and a custom button; you may retrieve the current settings for these options using the SCGetInfo function.

You supply a pointer to an extended functions structure. If you are retrieving these settings, the standard dialog component places the current settings into the specified structure; if you are changing the settings, place the new values into the structure; the component uses those values to update its settings. Set this pointer to nil to remove the current functions.

By default, none of these extended interface elements are used.

The SCExtendedProcs data type defines the format and content of the extended functions structure:

typedef struct {

    SCModalFilterProcPtr    filterProc;     /* filter function */

    SCModalHookProcPtr      hookProc;       /* hook function */

    long                    refcon;         /* reference constant */ 

    Str31                   customName;     /* custom button name */ 

} SCExtendedProcs;

This is how to declare a filter function named MyFilter:

pascal Boolean MyFilter (DialogPtr theDialog,

    EventRecord *theEvent, short *itemHit, long refcon);

This is how to declare a hook function named MyHook:

pascal short MyHook (DialogPtr theDialog,

    short *itemHit, SCParams *params, long refcon);

In both cases the refcon parameter accepts the reference constant that you supply in the refcon field of the extended functions structure.

Preference Flags Request Type

Use the preference flags request to specify or retrieve the standard dialog component’s preference flags. These flags govern some of the details of the dialog box that are presented to the user.

You supply a pointer to a long integer. If you are retrieving these flags, the standard dialog component places the current settings into the specified field; if you are changing the flags, set the field with your desired flag values; the component uses those values to update its settings.

By default, the SCRequestImageSettings function operates with the scShowBestDepth and scUseMovableModal flags set to 1. The SCRequestSequenceSettings function operates with the scUseMovableModal flag set to 1. You should never need to change the values of the scListEveryCodec or scUseMovableModal flags.

The following flags are defined:

#define  scListEveryCodec           (1L<<1)  /* list every component */

#define  scAllowZeroFrameRate       (1L<<2)  /* allow 0 frame rate */

#define  scAllowZeroKeyFrameRate    (1L<<3)  /* 0 key frame rate OK */

#define  scShowBestDepth            (1L<<4)  /* use best image depth */

#define  scUseMovableModal          (1L<<5)  /* use movable dialog */

Settings State Request Type

Use the settings state request to set or retrieve the configuration of the standard dialog component. You may use this request to retrieve the configuration information so that you can save it for later use, or to reconfigure the component based on a saved configuration.

Your application is not concerned with the content of the configuration information that is returned. The standard dialog component saves its configuration in a format that it understands. This request affects only those settings that are valid across system restarts, such as the spatial and temporal compression parameters and the data-rate settings.

You supply a pointer to a handle. When you retrieve the settings, the standard dialog component creates an appropriately-sized handle and places its current configuration information into the handle. Your application is responsible for disposing of the handle when you are done with it.

When you modify the settings, you supply the configuration information in the handle. The component copies the data out of this handle. Your application is responsible for disposing of the handle when you are done with it. Set the pointer to nil to reset the component to its default configuration.

Sequence ID Request Type

Use the sequence ID request type to retrieve the sequence identifier being used by the component’s SCCompressSequenceFrame function. You may not use this request to set the sequence identifier.

You supply a pointer to a field of type ImageSequence (this is an Image Compression Manager data type). The standard dialog component returns the current sequence identifier in that field.

Window Position Request Type

Use the window position request to position the user’s dialog box.

You supply a pointer to a point. If you are retrieving this information, the standard dialog component places the coordinates of the upper-left corner of the dialog box into this point; if you are changing the dialog box’s position, place the new coordinates into the point structure; the component uses those coordinates to position the dialog box.

Normally you should not need to use this request. By default, the standard dialog component centers the dialog box on the screen that is best-suited to display your test image. The component also saves the last window position for movable modal dialogs.

Control Flags Request Type

Use the control flags request to retrieve or modify the control flags used by the standard dialog component. The standard dialog component passes these flags through to the image compressor it uses to compress your image or sequence.

You supply a pointer to a flags field of data type CodecFlags (this is an Image Compression Manager data type). If you are retrieving the flags, the standard dialog component places the current flags into this field. If you are setting new flag values, place your desired settings into the field; the component uses these new flag settings.

By default, the standard dialog component sets all flags to 0 when it compresses still images. When it is compressing sequences, the component sets the codecFlagsPreviousUpdate and codecFlagsUpdatePreviousComp flags to 1. Typically, you should not need to change these flag settings.

Displaying the Standard image compression Dialog Box

Standard image compression dialog components provide two functions that allow you to display the standard dialog box to the user and retrieve the compression parameters specified by the user.

Use the SCRequestImageSettings function to retrieve the user’s preferences for compressing a single image; use the SCRequestSequenceSettings functions when you are working with an image sequence.

Both of these functions manipulate the compression settings that the component stores for you. The component may derive the current settings from a number of different sources:

• You may supply an image to the component from which it can derive default settings. You do this by using one of the functions discussed in Getting Default Settings for an Image or a Sequence.

• If you have not set any defaults, but you do supply a test image for the dialog, the component examines the test image and derives appropriate default values based upon its characteristics.

• If you have not set any defaults and do not supply a test image, the component uses its own default values.

• You may modify the settings by using the SCSetInfo function.

• You may allow the user to modify those settings by calling one of the functions discussed in this section.

You may customize the dialog boxes by specifying a modal-dialog hook function or a custom button. You may use the custom button to invoke an ancillary dialog box that is specific to your application. See Request Types for more information.

Compressing Still Images

The standard dialog component provides three functions you may use to compress a still image. These functions differ based on how the image is stored: SCCompressImage works with pixel maps; SCCompressPicture compresses a picture that is stored in a handle; and SCCompressPictureFile works with pictures stored in files.

All of these functions use the current compression settings. See Displaying the Standard image compression Dialog Box for detailed information about establishing these current settings.

If there are no default settings, each of these functions could potentially display a dialog box for single-frame compression operations.

Compressing Image Sequences

The standard dialog component provides three functions you may use to compress an image sequence. The SCCompressSequenceBegin function allows you to start a sequence-compression operation; use the SCCompressSequenceFrame function for each image in the sequence; you end the sequence by calling the SCCompressSequenceEnd function. The standard dialog component manages all of the compression details for you. Your application may have only one sequence-compression operation active on any given connection; naturally, you may have more than one connection active at a time.

All of these functions use the current compression settings. See Displaying the Standard image compression Dialog Box for detailed information about establishing these current settings.

If there are no default settings, each of these functions could potentially display a dialog box for sequence-compression operations.

Specifying a Test Image

The standard image compression dialog component provided by Apple supports a test image. The dialog box contains a small image along with the other parts of the dialog box. The component uses this image to display the effect of the user’s image compression settings. In this manner, the user can experiment with different settings and see the results of those settings immediately.

The component provides three functions that allow you to specify the test image. Use the SCSetTestImagePictHandle function if your test image is stored in a handle. Use the SCSetTestImagePictFile function if your test image is in a picture file. The SCSetTestImagePixMap function sets the test image from a pixel map.

Positioning Dialog Boxes and Rectangles

Standard image compression dialog components provide functions that allow you to position rectangles and dialog boxes. These functions are most useful in helping you to manage dialog boxes that are related to the standard image compression dialog. For example, your application might support a custom button that initiates a dialog box with the user to specify additional compression parameters. You can use these functions to position that dialog box in relation to the standard image compression dialog box.

There are two positioning functions: the SCPositionRect function positions a rectangle; the SCPositionDialog positions a dialog box. The SCGetBestDeviceRect function returns information about the best available display device.