test

KCMS CMM Developer's Guide

Configuration Requirements

This section tells you what you need to know to load your CMM. It explains how to name derived classes and how to update the OWconfig file for each derived class in your CMM.

CMM Filename Convention

A module (or CMM) name should follow this convention: 

kcs<STOCK

SYMBOL><CLASS><unique

identifier>.so.<version>

Table 2-1 describes each field in the CMM filename.

Table 2-1 CMM Filename Description

Filename Field 

Description 

kcs

Color management framework. 

stock symbol

Short mnemonic used by the stock market or a unique identifier. 

class

Class from which the module is derived (IO, Prof, Pfmt, Xform, or Stat).

unique identifier

Four-character identifier that distinguishes multiple modules derived from the same class. 

.so

Shared object library. 

version

Number compared to the KCS_MAJOR_VERSION number (incremented by SunSoft for every major release; for bundling CMMs only). 

Note -

The version number in the #define and the version number in the module name must match. See icc.h for an example.

Table 2-2 lists a few KCMS CMM filenames.

Table 2-2 KCMS CMM Filenames

CMM Filename 

Description 

kcsSUNWIOsolf.so.1

Solaris File CMM component 

kcsSUNWIOxwin.so.1

X11 Window System CMM component 

kcsSUNWStatsolm.so.1

Solaris Message CMM component, which accompanies each of the above CMM files for messages 

CMM Makefile

You must install your CMM in /usr/openwin/etc/devhandlers. To copy the file into this directory, you must be superuser and you must set the file permissions to 755 so that it is executable.

See the sample makefile in /opt/SUNWddk/kcms/src for an illustration of how CMMs are compiled and installed, and how the CMM library names are associated with the CMM modules.

Creating OWconfig File Entries

You must include OWconfig library in the CMM linking. To link in this library, enter -lowconfig on the link command line . The OWconfig library is bundled with Solaris in /usr/openwin/lib/libowconfig.so. It provides routines to access the OWconfig file, which gets the name of the CMM class derivitive you want to dynamically load.

To advertise its existence of your CMM class derivative to the KCMS framework, you must add the name of the derivitive to the OWconfig file.

A generic OWconfig entry looks like this: 

class="KCS_IO"

name="solf"

	kcsLoadableModule="kcsSUNWIOsolf.so.1";

Table 2-3 describes each field.

Table 2-3 OWconfig File Entry Description

OWconfig File Entry

Description 

class

KCS_<class name>.

name

Four- or eight-character identifier that matches the identifier in your code. 

kcsLoadableModule

Entire module name. 

The above is just an example of the OWconfig file structure. You need to add an OWconfig file entry for each class you derive from or extend in your CMM. Examples of these entries are shown in the following paragraphs.

KcsIO Example

If you derive from the KcsIO class, you need to provide a KcsIO class entry such as the example entries below: 

#KcsIO

class, Solaris profiles class="KCS_IO" name="solf"

	kcsLoadableModule="KcsSUNWIOsolf.so.1";  #KcsIO class, X11 window

system profiles class="KCS_IO" name="xwin"

	kcsLoadableModule="kcsSUNWIOxwin.so.1";

Note the name strings in the above examples. The KcsProfileType enumeration in kcstypes.h contains a type field that is a 4-character array described in hexadecimal form as a long, for example: 

typedef

enum { 	KcsFileProfile					= 0x46696C65, /*File*/ 	KcsMemoryProfile					=

0x4D426C00, /*MBl*/ #ifdef KCS_ON_SOLARIS 	KcsWindowProfile					= 0x7877696E,

/*xwin*/ 	KcsSolarisProfile					= 0x736F6C66, /*solf*/ #else

	KcsWindowProfile					= 0x57696E64, /*Wind*/ #endif /* KCS_ON_SOLARIS */

	KcsProfileTypeEnd					= 0x7FFFFFFF, 	KcsProfileTypeMax					= KcsForceAlign

}KcsProfileType;

The OWconfig library turns the type field back into a string corresponding to the name field entry and searches all of the appropriate OWconfig class entries for that string.

KcsProfile Example

If you derive from the KcsProfile class, you need to provide a KcsProfile class entry such as the example entries below:

#KcsProfile

Class, Solaris default is KCMS #Default profile class, CMM Id == Profile

Format class="KCS_Prof" name="dflt"

	kcsLoadableModule="kcsEkProfkcms.so.1";  #KCMS profile, CMM Id ==

Profile Format class="KCS_Prof" name="KCMS"

	kcsLoadableModule="kcsEKProfkcms.so.1";

The key to loading a new version is the CMM Id (also called CMM Type), which is contained in bytes 4 through 7 in the ICC profile header). (See "ICC Profile Header " for details.) If there is not a match, the default entry dflt is used. You must load the proper CMM Id into the new profile's CMM Id attribute field for recognition of the module.

The default loadable KcsProfile module is the Solaris-supplied default.

The KcsProfile class is the base class that can contain transformations (KcsXform class) and a profile format (KcsProfileFormat class). Since the Kodak KcsProfile class is built into the library, you can use this mechanism to extend the calibration and characterization interface.

KcsProfileFormat Example

If you derive from the KcsProfileFormat class, you need to provide a KcsProfileFormat class entry such as the example entries below:

#Profile

format class, default is ICC #Default profile format, ICC, default CMM

class="KCS_Pfmt" name="acspdflt"

	kcsLoadableModule="kcsEKPfmticc30.so.1";  #ICC profile format,

KCMS CMM class="KCS_Pfmt" name="acspKCMS"

	kcsLoadableModule="kcsEKPfmticc30.so.1";

The profile format is determined from the profile file signature (also known as the magic number), which is contained in bytes 36-39 in the ICC profile header), and CMM Id (bytes 4-7 in the header). (See "ICC Profile Header " .) A check is performed to ensure that an ICC profile uses the magic number of the file. If another format is used, the magic number is used to load the module.

All profiles that are ICC profile format files should have a magic number equal to acsp, and they must have the ICC header included. The CMM Id is used to match the profile format with the correct derivative. If no match is found, the default entry (dflt) is used; therefore, you can use the supplied default profile format class for ICC profiles.

The name field syntax is: <Profile magic number><CMM Id>

The OWconfig file entry must match the resulting name. This also gives color management vendors the opportunity to support pre-ICC format profiles, provided they include the ICC header.

KcsXform Example

If you derive from the KcsXForm class, you need to provide a KcsXForm class entry such as the example entries below:

#ICC

interpolation table 8 bit, default CMM class="KCS_Xfrm"

name="mft1dflt"

	kcsLoadableModule="kcsEKXfrmucp.so.1";  #ICC interpolation table

16 bit, default CMM class="KCS_Xfrm" name="mft2dflt"

	kcsLoadableModule="kcsEKXfrmucp.so.1";  #ICC interpolation table

8 bit, default CMM class="KCS_Xfrm" name="mft1KCMS"

	kcsLoadableModule="kcsEKXfrmucp.so.1";  #ICC interpolation table

16 bit, default CMM class="KCS_Xfrm" name="mft2KCMS"

	kcsLoadableModule="kcsEKXfrmucp.so.1";  #KCMS universal color

processor table class="KCS_Xfrm" name="ucpKCMS"

	kcsLoadableModule="kcsEKXfrmucp.so.1";

The name field is a combination of a unique 4-character transform identifier and the CMM Id. (The transform identifier must be registered with the ICC if the profile and CMM are to be made available to the public.) The library turns name back into a string and searches all of the appropriate OWconfig class entries.

Inside an ICC profile, the type of transform is defined by a type identifier that indicates whether it is an 8- or 16-multi function table, indicated by the signature element of either the Lut8Type (mft1) or Lut16Type (mft2). Default values have been supplied for these cases: mft1dflt and mft2dflt.

KcsStatus Example

If you extend the KcsStatus class, you need to provide a KcsStatus class entry such as the example below:

#Extending

error messages class="KCS_STAT" name-"solm"

	kcsLoadableModule="kcsSUNWSTATsolm.so.1";

The name field is a 4-character string that uniquely identifies your set of error and warning messages.

To add your own error messages, supply a single "C" routine that translates your error value into an error string. Also supply a messages.po file for localization purposes. See Chapter 8, KcsStatus Extension " for detailed information.

If an OwnerId variable is set with the status message, the KcsStatus class dynamically loads the matching OwnerId that was set by the dynamically loaded class. The OwnerID is described in Chapter 8, KcsStatus Extension .

Updating the OWconfig File

Using the interactive program called OWconfig_sample, which is provided with the DDK, you can insert and remove configuration entries (class, name, and kcsLoadableModule) in the OWconfig file.

To update OWconfig file entries, you must be root. If you are not root or the /etc/openwin/server/etc path does not exist, the following error is generated:

OWconfile

file not created/updated. Check that you are root and /etc/openwin/server/etc

exists.

Start the OWconfig_sample program as follows: 

example%

su example# ./OWconfig_sample

Inserting Entries

The following is an example of how to insert a configuration entry into the OWconfig file. Sample user responses are enclosed in brackets ([]).

Example 2-1 Inserting an OWconfig File Entry

ATTENTION:You must be

root to update the OWconfig file. Are you inserting an OWconfig entry? y/n 

[y]  You will be asked to supply a class, a name and a kcsLoadableModule to

create an entry such as the following: class = "SUN_Xfrm" name =

"acspdndp" kcsLoadable Module = "sunSUNWxfrmdndp.so.1"

Please see the KCMS CMM Developer's Guide for information  Enter the

profile class name in the form of XXX_IO, XXX_Prof, XXX_Prfmt, XXX_Xfrm, or

XXX_Stat. XXX is your unique cmm identifier, which must match the class name

of your derived class.  [KCS_Prof]  Enter the name of your cmm - it must match

the name in your derived class.  [dndp]  Enter the name of your dynamically

loadable module.  [kcsSUNWProfdndp.so.1]  This is your OWconfig entry. OK? y/n

 class = KCS_Prof name = dndp kcsLoadableModule = kcsSunWProfdndp.so.1  [y] 

Do you have more entries to create? y/n  [n]

The OWconfig_sample program above appends the entry to the OWconfig file.

Try inserting the entry shown in the above example:

  1. Run the OWconfig_sample program. Be sure you are root.

    See "Updating the OWconfig File " .

  2. Insert the user responses shown in Example 2-1 .

  3. Check for the entry at the end of the OWconfig file.

    The new configuration entry is appended to the end of the /usr/openwin/server/etc/OWconfig file. For local machine use only, the /etc/openwin/server/etc/OWconfig file is updated.

Removing Entries

The following is an example of how to remove a configuration entry from the OWconfig file. Sample user responses are enclosed in brackets ([]).

Example 2-2 Removing An OWconfig File Entry

ATTENTION:You must be

root to update the OWconfig file. Are you inserting an OWconfig entry? y/n 

[n]  To remove an OWconfig entry:  Enter the unique class name for your module

for removal from the OWconfig file. The class name would be in the form

XXX_IO, XXX_Prof, XXX_Pfrmt, or XXX_Stat  [KCS_Prof]  Enter the unique cmm

name for your module for removal from the OWconfig file.  [dndp]  This is the

OWconfig entry to remove. OK? y/n  class = KCS_Prof name = dndp  [y]  Do you

have more entries to remove? y/n  [n]

The OWconfig_sample program removes the last entry in the OWconfig file.

Try removing the entry you inserted following Example 2-1 :

  1. Run the OWconfig_sample program again. Be sure you are root.

    See "Updating the OWconfig File " .

  2. Fill in the user responses shown in Example 2-2 .

  3. Check the OWconfig file.

    The entry should no longer appear at the end of the file.

Version Numbering

Once OWconfigGetAttribute()() returns the module name, the version number is parsed out of the module name and compared to the global library version number located in kcsos.h to determine if this version can be executed.

Note -

The major version number in the module name must match the global variable located in the header file kcsrpc.h for an example.