Preface

The KCMS Application Developer's Guide describes the Kodak Color Management System (KCMS^(TM)) framework C-language application programming interface (API). The KCMS framework enables the accurate reproduction, and improves the appearance of, digital color images on desktop computers and associated peripherals. With the framework's "C" API, you can write applications that perform correct color conversions and manipulations.

Who Should Use This Guide

The intended audience of this guide is the professional programmer who is fluent in the C programming language and writing an application that:

Uses color data
Prints images
Is an imaging tool
Uses PhotoCD

Note - Although the KCMS API is a "C" language interface to the KCMS framework, you can write your application in other languages such as C++ by following the guidelines for making C-language calls.

Before You Read This Guide

Check the following documentation for any corrections or updates to the information in this guide:

See the on-line SUNWrdm packages for information on bugs and issues, engineering news, and patches. For Solaris installation bugs and for late-breaking bugs, news, and patch information, see the Installation Instructions for Solaris 2.6 (SPARC Platform Edition) and the Installation Instructions for Solaris 2.6 (Intel Platform Edition).

For SPARC^(TM) systems, consult any updates your hardware manufacturer provided.

Although you do not have to be a color scientist to write applications with the KCMS API, a certain amount of color literacy is helpful. Table P-1 lists two white papers that contain some basic information on color and KCMS. The files are located online in the /usr/openwin/demo/kcms/docs/ directory.

Table P-1

File Name	Title
`kcms-wp.ps`	*An Introduction to the Kodak Color Management System*
`kcms-wp-solaris.ps`	*Kodak Color Management System*

The KCMS framework this guide describes uses the International Color Consortium (ICC) format as the default format for color manipulation. For details on ICC, you should read the International Color Consortium Profile Format Specification. The ICC profile format specification is located by default in the icc.ps file in the /opt/SUNWsdk/kcms/doc directory. This is the specification to which this version of KCMS conforms. For the most current version of the ICC specification, see the web site at http://www.color.org.

Related Manuals

The following manuals will help you further understand the Driver Developer Kit (DDK) portion of the KCMS software product.

The following manuals will help you further understand the Calibrator Tool portion of the KCMS software product.

Solaris Advanced User's Guide
In Chapter 10, "Customizing Your Environment," there is a section called "Calibrating Your Monitor." The section tells you how to adjust your viewing environment and how to calibrate your monitor with Calibrator Tool.
KCMS Calibrator Tool Loadable Interface Guide
This guide will help you further understand the API to the Calibrator Tool. You can tailor the Calibrator Tool for your specific calibrator hardware and software with this API.

How This Guide Is Organized

This guide consists of the following chapters and appendix:

Chapter 1, "Introduction" explains the KCMS architecture and programming environment. In addition, it introduces you to several on-line sample programs that demonstrate the use of the KCMS API.
Chapter 2, "Profiles" explains profiles, which are the focus of your programming efforts with the KCMS framework.
Chapter 3, "Data Structures" describes the data structures of the KCMS framework.
Chapter 4, "Functions" details each KCMS "C" API function.
Chapter 5, "KCMS Profile Attributes" details each profile attribute (tag).
Chapter 6, "Warning and Error Messages" describes status codes (error and warning messages) returned by the KCMS framework functions.

Ordering Sun Documents

The SunDocs^SM program provides more than 250 manuals from Sun Microsystems, Inc. If you live in the United States, Canada, Europe, or Japan, you can purchase documentation sets or individual manuals using this program.

For a list of documents and how to order them, see the catalog section of the SunExpress^(TM) Internet site at http://www.sun.com/sunexpress.

Note - The term "x86" refers to the Intel 8086 family of microprocessor chips, including Pentium and Pentium Pro processors and compatible microprocessor chips made by AMD and Cyrix. In this document, the term "x86" refers to the overall platform architecture, whereas "Intel Platform Edition" appears in the product name.

What Typographic Changes Mean

The following table describes the typographic changes used in this guide.

Table P-2

Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% You have mail.`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name%` `su` `Password:`
*AaBbCc123*	Command-line placeholder: replace with a real name or value	To delete a file, type `rm` *filename*.
*AaBbCc123*	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in *User's Guide. These are called class* options. You *must* be root to do this.

KCMS Naming Conventions

The KCMS "C" API naming conventions shown in Table P-3 are used throughout the KCMS framework and this guide.

Table P-3

Item	Convention	Examples
Attribute names	ICC profile format attribute names begin with "`ic`"--`ic`<*AttributeName*>	`icHeader`
Data structures Typedefs Constants	ICC profile format data structures begin with "`ic`". All other data structures, typedefs, and constants are KCMS specific and begin with "`Kcs`"--`Kcs`<*TypeDefName*>	`icTextDescription` `KcsCalibrationData`
Functions	Each significant word in a function name is capitalized. Intervening spaces are removed--`Kcs`<*FunctionName*>()	`KcsConnectProfiles()`
Macros	Macros are KCMS specific and are capitalized--`KCS_`<*MACRO_NAME*>	`KCS_DEFAULT_ATTRIB_COUNT`
Status codes	All status codes are capitalized and have the format `KCS_`<*STATUS_CODE*>	`KCS_PROF_ID_BAD`

Note - Historically KCMS was referred to by the abbreviation KCS (or Kcs). This abbreviation has been carried forward as the prefix in KCMS data type names, for example, KcsCalibrationData.

Equivalent Terms In This Guide

For historic reasons, this guide uses several equivalent Kodak and ICC terms. The terms evolved at different times. Development of the ICC specification introduced new ICC terms with meanings the same as (or similar to) already existing Kodak terms.

You should be familiar with the terms listed in the table below, as you will encounter them in the ICC specification and KCMS color management documentation, as well as in the KCMS header files and example programs. The terms are defined as they are introduced in this guide.

Table P-4

Kodak Term	ICC Term
attribute	tag
device color profile (DCP)	input, display, or output profile
effects color profile (ECP)	abstract profile
complete color profile (CCP)	device link profile
reference color space (RCS)	profile connection space (PCS)

Note - The text in this guide uses the term attribute instead of tag, (but code examples and header files may use tag for the historic reasons previously mentioned.

Shell Prompts in Command Examples

The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P-5

Shell	Prompt
C shell prompt	`machine_name%`
C shell superuser prompt	`machine_name#`
Bourne shell and Korn shell prompt	`$`
Bourne shell and Korn shell superuser prompt	`#`