PATHMac OS 8 Developer Documentation > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Application-Defined Functions for the ColorSync Manager

Your application supplies the following functions for use with ColorSync Manager functions. The ColorSync Manager functions that use your functions take a universal procedure pointer to your function as an input parameter.


MyProfileIterateProc

New in ColorSync 2.5

Application-defined function that the CMIterateColorSyncFolder function calls once for each found profile file as it iterates over the available profiles. Used, for example, to obtain a list of profiles to display in a pop-up menu.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal OSErr MyProfileIterateProc (
                     CMProfileIterateData *iterateData,
                     void *refCon);
iterateData
A pointer to a structure of type CMProfileIterateData . When the function CMIterateColorSyncFolder calls MyProfileIterateProc , as it does once for each found profile, the structure contains key information about the profile.
refCon
An untyped pointer to arbitrary data your application previously passed to the function CMIterateColorSyncFolder .
function result
A result code of type OSErr . If MyProfileIterateProc returns an error, CMIterateColorSyncFolder stops iterating and returns the error value to its caller (presumably your code). For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

When your application needs information about the profiles currently available in the profiles folder, it calls the function CMIterateColorSyncFolder , which, depending on certain conditions, calls your callback routine once for each profile. See the description of CMIterateColorSyncFolder for information on when it calls the MyProfileIterateProc routine.

Your MyProfileIterateProc routine examines the structure pointed to by the iterateData parameter to obtain information about the profile it describes. The routine determines whether to do anything with that profile, such as list its name in a pop-up menu of available profiles.


MyColorSyncDataTransfer

Changed in ColorSync 2.5

Application-defined function that transfers profile data from the format for embedded profiles to disk file format or vice versa. Used, for example, by PostScript functions to transfer data from a profile to text format usable by a PostScript driver.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal OSErr MyColorSyncDataTransfer (
                     long command,
                     long *size,
                     void *data,
                     void *refCon);
command
The command with which the MyColorSyncDataTransfer function is called. This command specifies the operation the function is to perform.
size
A pointer to a size value. On input, the size in bytes of the data to transfer. On output, the size of the data actually transferred.
data
A pointer to the buffer supplied by the ColorSync Manager to use for the data transfer.
refCon
A reference constant that holds the application data passed in from the functions CMFlattenProfile , CMUnflattenProfile , CMGetPS2ColorSpace , CMGetPS2ColorRenderingIntent , or CMGetPS2ColorRendering . Each time the CMM calls your MyColorSyncDataTransfer function, it passes this data to the function. Starting in ColorSync version 2.5, the ColorSync Manager calls your function directly, without going through the preferred, or any, CMM.
function result
A result code of type OSErr . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Starting in ColorSync version 2.5, the ColorSync Manager calls your data transfer function directly, without going through the preferred, or any, CMM. So any references to the CMM in the discussion that follows are applicable only to versions of ColorSync prior to version 2.5. Where the discussion does not involve CMMs, it is applicable to all versions of ColorSync.

Your MyColorSyncDataTransfer function is called to flatten and unflatten profiles or to transfer PostScript-related data from a profile to the PostScript format to send to an application or device driver.

The ColorSync Manager and the CMM communicate with the MyColorSyncDataTransfer function using the command parameter to identify the operation to perform. To read and write profile data, your function must support the following commands: openReadSpool , openWriteSpool , readSpool , writeSpool , and closeSpool .

You determine the behavior of your MyColorSyncDataTransfer function. The following sections describe how your function might handle the flattening and unflattening processes.

Flattening a Profile

The ColorSync Manager calls the specified profile's preferred CMM when an application calls the CMFlattenProfile function to transfer profile data embedded in a graphics document.

The ColorSync Manager determines if the CMM supports the CMFlattenProfile function. If so, the ColorSync Manager dispatches the CMFlattenProfile function to the CMM. If not, ColorSync calls the default CMM, dispatching the CMFlattenProfile function to it.

The CMM communicates with the MyColorSyncDataTransfer function using a command parameter to identify the operation to perform. The CMM calls your function as often as necessary, passing to it on each call any data transferred to the CMM from the CMFlattenProfile function's refCon parameter.

The ColorSync Manager calls your function with the following sequence of commands: openWriteSpool , writeSpool , and closeSpool . Here is how you should handle these commands:

As part of this process, your function can embed the profile data in a graphics document, for example, a PICT file or a TIFF file. For example, your MyColorSyncDataTransfer function can call the QuickDraw PicComment function to embed the flattened profile in a picture.

Unflattening a Profile

When an application calls the CMUnflattenProfile function to transfer a profile that is embedded in a graphics document to an independent disk file, the ColorSync Manager calls your MyColorSyncDataTransfer function with the following sequence of commands: openReadSpool , readSpool , closeSpool . Here is how you should handle these commands:

VERSION NOTES

Starting in ColorSync version 2.5, the ColorSync Manager calls your function directly, without going through the preferred, or any, CMM.


MyCMBitmapCallBackProc

Application-defined function that reports on the progress of a color-matching or color-checking session being performed for a bitmap or a pixel map.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal Boolean MyCMBitmapCallBackProc (
                     long progress,
                     void *refCon);
progress
A byte count that begins at an arbitrary value when the function is first called. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. If the function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.
refCon
The reference constant passed to your MyCMBitmapCallBackProc function each time the color management module (CMM) calls your function.
function result
A result code of type Boolean . A return value of false indicates the color-matching or color-checking session should continue. A return value of true indicates the session should be aborted--for example, the user may be holding down the Command-period keys.

DISCUSSION

Your MyCMBitmapCallBackProc function allows your application to monitor the progress of a color-matching or color-checking session for a bitmap or a pixel map. Your function can also terminate the matching or checking operation.

Your callback function is called by the CMM performing the matching or checking process if your application passes a pointer to your callback function in the progressProc parameter when it calls one of the following functions: CWMatchPixMap , CWCheckPixMap , CWMatchBitmap , and CWCheckBitMap . Note that your callback function may not be called at all if the operation completes in a very short period.

The CMM used for the color-matching session calls your function at regular intervals. For example, the default CMM calls your function approximately every half-second unless the color matching or checking occurs in less time; this happens when there is a small amount of data to match or check.

Each time the ColorSync Manager calls your function, it passes to the function any data stored in the reference constant. This is the data that your application specified in the refCon parameter when it called one of the color-matching or checking functions.

For large bitmaps and pixel maps, your application can display a progress bar or other indicator to show how much of the operation has been completed. You might, for example, use the reference constant to pass to the callback function a window reference to a dialog box. You obtain information on how much of the operation has completed from the progress parameter. The first time your callback is called, this parameter contains an arbitrary byte count. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. Using the current value and the original value, you can determine the percentage that has completed. If the callback function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.

To terminate the matching or checking operation, your function should return a value of true . Because pixel-map matching is done in place, an application that allows the user to terminate the process should revert to the prematched image to avoid partial mapping.

For bitmap matching, if the matchedBitMap parameter of the CWMatchBitmap function specifies NULL , to indicate that the source bitmap is to be matched in place, and the application allows the user to abort the process, you should also revert to the prematched bitmap if the user terminates the operation.

Each time the ColorSync Manager calls your progress function, it passes a byte count in the progress parameter. The last time the ColorSync Manager calls your progress function, it passes a byte count of 0 to indicate the completion of the matching or checking process. You should use the 0 byte count as a signal to perform any cleanup operations your function requires, such as filling the progress bar to completion to indicate to the user the end of the checking or matching session, and then removing the dialog box used for the display.


MyCMProfileFilterProc

Application-defined function that examines the profile whose reference you specify and determines whether to include it in the profile search result list.

After a profile has been included in the profile search result based on criteria specified in the search record, your MyCMProfileFilterProc function can further examine the profile. For example, you may wish to include or exclude the profile based on criteria such as an element or elements not included in the CMSearchRecord search record. Your MyCMProfileFilterProc function can also perform searching using AND or OR logic.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal Boolean MyCMProfileFilterProc (
                     CMProfileRef prof,
                     void *refCon);
prof
A profile reference of type CMProfileRef to the profile to test.
refCon
A reference constant that holds data passed through from the CMNewProfileSearch function or the CMUpdateProfileSearch function.
function result
A result code of type Boolean . A return value of false indicates that the profile should be included. A return value of true indicates that the profile should be filtered out.

DISCUSSION

Your MyCMProfileFilterProc function is called after the CMNewProfileSearch function searches for profiles based on the search record's contents as specified by the search bitmask.

When your application calls CMNewProfileSearch , it passes a reference to a search specification record of type CMSearchRecord of type CMSearchRecord that contains a filter field. If the filter field contains a pointer to your MyCMProfileFilterProc function, then your function is called to determine whether to exclude a profile from the search result list. Your function should return true for a given profile to exclude that profile from the search result list. If you do not want to filter profiles beyond the criteria in the search record, specify a NULL value for the search record's filter field.


MyCMProfileAccessProc

Application-defined function that provides procedure-based access to a profile.

When your application calls the CMOpenProfile , CMNewProfile , CMCopyProfile , or CMNewLinkProfile functions, it may supply the ColorSync Manager with a profile location structure of type CMProfileLocation that specifies a procedure that provides access to a profile. In the structure, you provide a universal procedure pointer to a profile access procedure supplied by you and, optionally, a pointer to data your procedure can use. The ColorSync Manager calls your procedure when the profile is created, initialized, opened, read, updated, or closed.

The profile access procedure supplied by your application must conform to the following declaration, although the procedure name is arbitrary.

pascal OSErr MyCMProfileAccessProc (
                     long command,
                     long offset,
                     long *size,
                     void *data,
                     void *refConPtr);
command
A command value indicating the operation to perform. Operation constants are described in Profile Access Procedure Operation Codes .
offset
For read and write operations, the offset from the beginning of the profile at which to read or write data.
size
A pointer to a size value. On input, for the cmReadAccess and cmWriteAccess command constants, a pointer to a value indicating the number of bytes to read or write; for the cmOpenWriteAccess command, the total size of the profile. On output, after reading or writing, the actual number of bytes read or written.
data
A pointer to a buffer containing data to read or write. On output, for a read operation, contains the data that was read.
refConPtr
A reference constant pointer that can store private data for the MyCMProfileAccessProc procedure.
function result
A result code of type OSErr . If an error occurs during processing, your routine returns the appropriate error value. If no error occurs, it returns noErr .

DISCUSSION

When the ColorSync Manager calls your profile access procedure, it passes a constant indicating the operation to perform. The operations include creating a new profile, reading from the profile, writing the profile, and so on. Operation constants are described in Profile Access Procedure Operation Codes . Your procedure must be able to respond to each of these constants.


© 1988-1999 Apple Computer, Inc. — (Last Updated 20 Jan 99)