![]() |
PATH![]() |
![]() ![]() |
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.
CMIterateColorSyncFolder
function as it iterates over the available profiles;
new in ColorSync 2.5
.MyColorSyncDataTransfer
transfers profile data from the format for embedded profiles to disk file format or vice versa.MyCMBitmapCallBackProc
reports on the progress of a color-matching or color-checking session being performed for a bitmap or a pixel map.MyCMProfileFilterProc
examines the profile whose reference you specify and determines whether to include it in the profile search result list.MyCMProfileAccessProc
provides procedure-based access to a profile.
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);
CMProfileIterateData
. When the function
CMIterateColorSyncFolder
calls
MyProfileIterateProc
, as it does once for each found profile, the structure contains key information about the profile.CMIterateColorSyncFolder
.
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.
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);
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.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.
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.
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:
Starting in ColorSync version 2.5, the ColorSync Manager calls your function directly, without going through the preferred, or any, CMM.
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);
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.
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);
CMProfileRef
to the profile to test.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.
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);
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.