KCMS Application Developer's Guide

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 online 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 Solaris 8 (SPARC Platform Edition) Installation Guide and the Solaris 8 (Intel Platform Edition) Installation Guide manuals.

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 on-line in the /usr/openwin/demo/kcms/docs/ directory.

Table P-1 KCMS White Papers


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 Books

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.

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

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.

KCMS Naming Conventions

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

Table P-2 API Naming Conventions


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 Table P-3, 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-3 Equivalent ICC and Kodak Terms


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

Ordering Sun Documents

Fatbrain.com, an Internet professional bookstore, stocks select product documentation from Sun Microsystems, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at http://www1.fatbrain.com/documentation/sun.

Accessing Sun Documentation Online

The docs.sun.com^SM Web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. The URL is http://docs.sun.com.

What Typographic Conventions Mean

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

Table P-4 Typographic Conventions


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.

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 Prompts


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	`#`