This chapter discusses the basic procedures that apply to the development of any Coloratura application. It also discusses useful tools that are included in the library: commands and sample code. These are the topics discussed:
To use the Coloratura library, which is implemented as a dynamically shared object, include the two header files cms.h and ic.h in your source code and compile your program with the switch -lcms.
The file cms.h defines data structures, function prototypes and parameters specific to the Coloratura CMS. You do not need to declare Coloratura data structures before you call Coloratura functions; this is done by including the file cms.h in your source code.
The file ic.h establishes data structures for the ICCColor Profile Format Specification.
Coloratura applications use one of two approaches to managing memory, depending on whether a given data object has a fixed size.
If a data object does not have a fixed size:
Use Coloratura functions to create the data storage and set a pointer value.
When you no longer need the data, call a Coloratura function to free the data. For each type of data, there is a specific function. For example, cmsGetCmmList() returns a variable-length list of available CMMs. Your application passes to cmsGetCmmList() the address of a pointer to the list, and frees the list by calling cmsFreeCmmList().
If a data object has a fixed size, you need no special Coloratura function to free storage; you can use standard ANSI C memory management functions.
If your application requires custom memory management, layer the management on top of the three standard ANSI C functions that are used by the Coloratura CMS: malloc(), free(), and realloc(). Using two different memory allocation schemes can cause problems such as memory leaks, data corruption, or core dumps. If you use other functions, check that all the memory allocators work together.
Every Coloratura function returns CMS_SUCCESS, if there are no errors.
Each Coloratura function has a set of specific error codes that it returns if there are errors. Before proceeding after a function call, you should always check the value returned.
The Coloratura CMS provides a standard message catalog in /usr/lib/locale/C/LC_MESSAGES. You can call the function pfmt() to interpret the error codes returned by Coloratura functions (see the reference pages pfmt(1) and pfmt(3C) for more details). Because the message catalog is accessed by line numbers, do not modify the catalog; if you need more error messages, create another catalog.
The Coloratura CMS maintains a certain amount of bookkeeping information that all Coloratura functions use. The information is stored in the data structure CMSContext, which is initialized by cmsOpen(). You must call cmsOpen() before you call any other Coloratura functions. When you are through with the CMS, call cmsClose() to free storage allocated by cmsOpen().
The pointer CMSContext refers to an opaque data structure that stores the internal working state of the Coloratura CMS and is used in all function calls. The data type declaration is:
typedef struct _CMSContext *CMSContext; |
The function cmsOpen() establishes a CMSContext that is an argument in all subsequent Coloratura calls. Call this function before you call any other Coloratura function. You pass the address of a CMSContext and cmsOpen() initializes it appropriately.
The function cmsOpen() searches the system to find out which CMMs are available and stores the information in the CMSContext. Your application cannot use any CMM that you add after a call to cmsOpen().
This is the prototype for cmsOpen():
int32 cmsOpen(CMSContext *pctxt); |
This is the active argument ofcmsOpen():
| pctxt | A pointer to the opaque data structure CMSContext. |
These are the error codes returned by cmsOpen():
| CMS_OUT_OF_MEMORY |
| |
| CMS_FAILURE |
|
Call cmsClose() when you are finished with the Coloratura CMS; no Coloratura function calls may be made afterwards. The function cmsClose() first requests that any open CMMs close themselves, and then it closes open resources and frees storage that the Coloratura CMS still controls. You must make your own calls to free memory that your application allocated and that cannot be freed by a Coloratura function.
This is the prototype for cmsClose():
int32 cmsClose(CMSContext ctxt; |
This is the active argument of cmsClose():
| ctxt | The context initialized by cmsOpen(). |
Along with the function library that you can use in your application, the Coloratura CMS provides several commands that perform useful, elementary operations: embedding profiles and simple color transformations of common image formats.
Below is a brief description of the commands. See the man pages for further details.
The following commands perform file format conversions that retain embedded ICC profile information:
cmssgi2jpg(1)
cmssgi2stiff(1)
The commands differ according to the image file format they produce; the format is indicated by the string following cmssgi2 in the command name.
The following commands all embed either a complete ICC device profile or its filename in one or more image files:
cmstag(1)
cmstaggif(1)
cmstagjpeg(1)
cmstagsgi(1)
cmstagstiff(1)
Embedding the filename is only useful if the image data and profile remain in the same file system.
The commands differ according to the image file format they act on; the format is indicated by the string following tag in the command name. cmstag embeds profile information in files of several different formats.
The following commands use ICC profiles to perform a color management operation ("color correction," hence "coco") on image files:
cocogif(1)
cocojpeg(1)
cocostiff(1)
The operation is a color space conversion from a specified input device color space to a specified output device color space. The image file format each command acts on is indicated by the string following coco.
These commands are essentially compiled variants of the sample code cocoifl, outlined in "Example Outline of a Color Conversion Program", and presented in Appendix B, "Listing of the Application cocoifl."
The Coloratura CMS includes several code examples to illustrate how to use the library in typical situations (see /usr/cms/examples/). The library also includes a test profile, which provides visual feedback indicating that a color transformation program is working properly.
This example code illustrates a basic color conversion program, using the Image Format Library to read most image files. The basic operations performed by cocoifl are described in "Example Outline of a Color Conversion Program". Appendix B, "Listing of the Application cocoifl," shows the source code.
These examples illustrate a special case of cocoifl: applying a device-link profile to image data. makedevlink is easily extended.
This example illustrates combining three profiles, an operation you would be likely to perform when simulating an output.
This profile provides a simple visual test that something happened in your color management application. This will not find flaws in a Coloratura application, as there are no exact digital values guaranteed, but the visual test gives a good indication of how (and whether) your application is performing.
The profile is like a monitor profile, but the tone curve is flipped. If you embed it in an image and use the default monitor profile, the image should look somewhat like a photographic negative. If the Coloratura CMS fails to process the image, you probably get back the original image.
Or you can make this profile your default monitor profile, by placing it in /var/cms/profiles/local and calling it monitor.pf. Then if your image has a source device profile embedded in it, you also see a "sort-of-negative" image.