< Previous PageNext Page > Hide TOC

Image Compression Dialog Types and Functions

This chapter describes the request types and functions associated with the standard image compression dialog components and an application-defined function.

In this section:

Request Types
Standard image compression Dialog Component Functions


Request Types

This section describes the request types used by two standard dialog component functions that allow you to work with the current compression settings for an image or a sequence of images. (You can establish these settings in a number of ways; see Setting Default Parameters for more information about your options.)

You use the SCGetInfo function to retrieve settings information. The SCSetInfo function enables you to modify the settings.

These functions can work with a number of different types of settings information. When you call either function, you specify the type of data you want to work with. The following request types are defined:

#define  scSpatialSettingsType    'sptl'      /* spatial options */
#define  scTemporalSettingsType   'tprl'      /* temporal options */
#define  scDataRateSettingsType   'drat'      /* data rate */
#define  scColorTableType         'clut'      /* color table */
#define  scProgressProcType       'prog'      /* progress function */
#define  scExtendedProcsType      'xprc'      /* extended dialog */
#define  scPreferenceFlagsType    'pref'      /* preferences */
#define  scSettingsStateType      'ssta'      /* all settings */
#define  scSequenceIDType         'sequ'      /* sequence ID */
#define  scWindowPositionType     'wndw'      /* window position */
#define  scCodecFlagsType         'cflg'      /* compression flags */

Each of these request types requires different parameter data. The following sections discuss each of these request types and their data requirements.

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;

Field

Description

codecType

Specifies the default compressor type that is displayed in the pop-up menu of compressors in the dialog box. The standard image compression dialog component uses this field to return the compressor type that was selected by the user. You must set this parameter to one of the compressor types supported by the Image Compression Manager, or to nil. If you set the field to nil, the standard image compression dialog component uses as the default value the first compressor or compressor type that it retrieves from the Image Compression Manager.

codec

Provides additional information about the default compressor that is displayed in the pop-up menu of compressors in the dialog box. If the user selects a specific compressor component, the standard image compression dialog component returns the appropriate compressor identifier in this field. Other options for this field are discussed below.

depth

Specifies the default value of the pixel depth pop-up menu in the dialog box. This menu allows the user to select the color or gray scale resolution value to be used when compressing the image or image sequence. If you set this field to 0, the component chooses an appropriate depth for the default compressor you specified with the theCodec field. When the user clicks OK, the standard image compression dialog component sets this field to the pixel depth value selected by the user. Note that the standard image compression dialog component may adjust the depth value so that it corresponds to a value that is supported by the compressor that has been selected by the user. The depth returned could be 0 if the scShowBestDepth flag is set.

spatialQuality

Specifies the default setting of the quality slider in the dialog box. This slider controls the spatial quality of the compressed image sequence, which influences the amount of spatial compression that can be achieved. Spatial compression eliminates redundant information within each frame in a sequence. When the user clicks OK, the standard image compression dialog component sets this field to the spatial quality value selected by the user. Note that the standard image compression dialog component may adjust the quality value so that it corresponds to a value that is supported by the compressor that has been selected by the user.

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;

Field

Description

temporalQuality

Specifies the default setting of the motion quality slider in the dialog box. This slider controls the temporal quality of the compressed image, which influences the amount of temporal compression that can be achieved (note that Apple's component uses the same slider for both spatial and temporal quality). Temporal compression eliminates redundant information between frames in an image sequence. When the user clicks OK, the standard image compression dialog component sets this field to the temporal quality value selected by the user. Note that the standard image compression dialog component may adjust the quality value so that it corresponds to a value that is supported by the compressor that has been selected by the user.

frameRate

Specifies the default value of the text-edit box that controls the number of frames per second in the image sequence to be compressed. This dialog item allows the user to select the frame rate to be used when compressing the image sequence. Note that this field is stored as a fixed-point number, allowing the user to specify fractional frame rates. When the user clicks OK, the standard image compression dialog component sets this field to the frame rate value specified by the user. If you have set the scAllowZeroFrameRate flag to 1 in the scPreferenceFlagsType request, and the user specifies nothing or 0, the component sets this field to 0. This dialog item can be useful in cases where your application cannot determine the frame rate of the source movie. For example, movies stored in PICT files do not include frame rate information. Therefore, the user must specify a frame rate for you. Alternatively, some users may want to create movies with different frame rates. This item allows the user to specify a rate for the compressed sequence.

keyFrameRate

Specifies the default value of the text-edit box that controls the frequency with which key frames are inserted into the compressed image sequence. Key frames provide points from which a temporally compressed sequence may be decompressed. When the user clicks OK, the standard image compression dialog component sets this field to the key frame rate value specified by the user. If you have set the scAllowZeroKeyFrameRate flag to 1 in the scPreferenceFlagsType request, and the user specifies nothing or 0, the component sets this field to 0.

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;

Field

Description

dataRate

Specifies the maximum number of bytes of compressed data your application wants to receive per second. Use this parameter to modulate the rate at which the component passes compressed data to your application. This can be useful to account for hardware limitations during sequence playback.

frameDuration

Indicates the duration of each frame, in milliseconds. Set this parameter to 0 to allow the standard dialog component to calculate the duration based upon the frame rate you specify in an scTemporalSettingsType request. However, if you allow the user to specify a 0 frame rate (that is, you set thescAllowZeroFrameRate flag to 1 in your scPreferenceFlagsType request), you must set the frame duration each time you compress a frame, because the component does not have sufficient information to determine an appropriate rate.

minSpatialQuality

Specifies the minimum acceptable spatial quality. In order to meet your specified data rate, the standard dialog component may have to adjust the spatial quality setting. Use this parameter to set a minimum level, which the component may not exceed.

minTemporalQuality

Specifies the minimum acceptable temporal quality. As with spatial quality, in order to meet your specified data rate, the standard dialog component may have to adjust the temporal quality setting. Use this parameter to set a minimum level, which the component may not exceed.

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;

Field

Description

filterProc

Contains a pointer to a modal-dialog filter function in your application. Because the compression dialog box is a movable modal dialog box, you must provide a filter to process update events for your application windows. The standard component calls your filter function before it processes the event. You can use this function to control events in the dialog box. For example, you might use the filter function to release processing time to other windows displayed by your application while the standard image compression dialog box is being displayed. If you do not want to specify a filter function, set this parameter to nil.

hookProc

Contains a pointer to a dialog hook function in your application. The standard component calls your hook function whenever the user selects an item in the dialog box. You can use this function to customize the operation of the standard image compression dialog box. For example, you might want to support a custom button that activates a secondary dialog box. Another possibility would be to provide additional validation support when the user clicks OK. If you do not want to specify a hook function, set this parameter to nil.

refcon

Specifies a reference constant that is to be passed to the dialog hook function and the modal-dialog filter function.

customName

Specifies the string to be displayed in the custom button in the dialog box. If you are not using a custom button, set this parameter to nil.

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 */

Flag

Description

scListEveryCodec

Controls the contents of the pop-up menu of compressors. If you set this flag to 1, the standard image compression dialog component lists every compressor component that is present in the system. Each entry in the list contains the name of a compressor component. The user may then select a specific component from the list. If you set this flag to 0, the list contains one entry for each type of compressor component that is present in the system. Each list entry contains the name of a compressor type (for example, a list entry might contain "Animation" for the animation compressor). The user may then choose a type of compressor and it is your application's responsibility to select an appropriate compressor of that type.

scAllowZeroFrameRate

Determines whether the component allows the user to specify a value of 0 for the frame rate. If you set this flag to 1, the component allows the user to specify either 0 or nothing for the frame rate. The component then includes a "best rate" entry in the pop-up menu. If the user specifies 0, the component sets the frameRate field in the SCTemporalSettings structure to 0. Your application must then determine the best frame rate for the movie. If you set this flag to 0, the component does not allow the user to enter 0 for the frame rate. In this case, the user must select a specific frame rate.

scAllowZeroKeyFrameRate

Similar to the scAllowZeroFrameRate flag, this flag determines whether the component allows the user to specify a value of 0 for the key frame rate. If you set this flag to 1, the component allows the user to specify 0 for the frame rate. If the user specifies 0, the component sets the keyFrameRate field in the SCTemporalSettings structure to 0. Your application must then determine the best key frame rate for the movie. If you set this flag to 0, the component does not allow the user to specify 0 for the frame rate. In this case, if the user has enabled temporal compression by checking the key frame checkbox, the user must also select a specific key frame rate.

scShowBestDepth

Determines whether the component includes a "best depth" entry in the pop-up menu for pixel depth. If you set this flag to 1, the component includes a "best depth" entry in the pop-up menu. If the user selects "best depth", the component sets the depth to 0. Your application must then determine the best pixel depth for the movie. If you set this flag to 0, the component does not include a "best depth" entry in the pop-up menu. The user must select a depth from among the other available choices.

scUseMovableModal

  Determines whether the standard compression dialog is a movable or a stationary dialog. Set this flag to 1 to create a movable dialog. In this case, you should provide an event filter function to handle update events (use the scExtendedProcsType request).

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.

Standard image compression Dialog Component Functions

This section describes the functions that are supported by standard image compression dialog components.

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 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.



< Previous PageNext Page > Hide TOC


© 2005, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-01-10)


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.