How Calibrator Tool Works With A Loadable Module

Software Components

There are two main software components to calibration: Calibrator Tool (main program) and one or more OEM-written loadable modules. Calibrator Tool is started with the kcms_calibrate(1) command. Then it works together with loadable modules to obtain color data and to update color profiles.

Calibrator Tool Responsibilities

Calibrator Tool obtains measurements to update a monitor's color profile. It obtains the data it needs from the loadable software module.

Calibrator Tool obtains the measurement data through two data structures that it passes to the loadable module. It allocates and deallocates the memory for the structures and sets up their formats based on the number and types of X11 visuals that the X Window System supports. Using standard X11 routines, it determines which X visuals are supported on the system. Then it creates a profile copy for each visual. Finally it hands off this information formally packaged in the data structures to the loadable module.

Once it retrieves the measurement data from the loadable module, Calibrator Tool updates the X visual profile copies on the local machine.

Loadable Module Responsibilities

The loadable module doesn't need to know anything about the color profiles or where they are stored. It simply performs the required measurements and fills out the data structures passed in by Calibrator Tool. Then it returns the information to the main program.

This is a simplification, of course. The module uses some mechanism for obtaining the calibration data from the monitor device. The KCMS portion of the Solaris SDK provides two sample dynamically loadable modules. One module (colorsense.so.1) requires the use of a hardware colorimeter connected to a serial port on the local system to obtain color data measurements. The other module obtains measurement data without a colorimeter. In either case, the module provides a GUI for interaction with an end user.

KCMS includes a loadable driver for the X-Rite DTP92 colorimeter. The driver is very similar to the colorsense() module described in this guide. It supports the X-Rite colorimeter, which connects to the serial port to obtain color measurement data.

Calibrator Tool and Loadable Module Interaction

Calibrator Tool and the loadable module interact with each other using three application programming interface (API) functions. These are

• KCMSCMonInit()

• KCMSCMonMeasure()

• KCMSCMonClose()

Each programming interface identifies a phase (initialization, data collection, or closure) in the interaction between Calibrator Tool and the loadable module. To indicate the success or failure of a phase, each module returns status information. A zero status value indicates success; any nonzero value indicates that an error has occurred. If a nonzero status value is returned at any point in the calibration process, the loadable module application is terminated and Calibrator Tool displays a status message. (For details on Calibrator Tool status messages, see the section entitled "Customizing Your Monitor" in Chapter 10, "Customizing Your Environment," in the OpenWindows Advanced User's Guide.) The loadable module may have its own custom error and status messages.

The following summarizes the three phases in the interaction between Calibrator Tool and the module.

Initialization

During initialization, Calibrator Tool takes a handle to the dynamically opened module and accesses the KCMSCMonInit symbolic name using dlsym(3X). If it finds the name, it initializes and allocates space for the visual data.

The tool calls KCMSCMonInit() to allow the loadable module to initialize the serial port for the hardware colorimeter (if it uses one to take measurements), to start its own GUI-based application, and to make any additional preparations necessary to measure monitor data.

The sample modules described in this guide set up the application user interface during initialization using included source code from TeleUSE (Motif GUI builder) and the X Toolkit library (available with Solaris 2.5 and later). (Refer to the colorsense() and XSolarisVisualGamma() source files.) Be aware that you are not required to use this code in the design of your module. The examples are an implementation only. All or parts of them can be used as a template, depending on your needs.

Data Collection

Calibrator Tool initializes and sets up the data structure to gather data. It makes standard X11 Window System calls to establish the number and types of X visuals for which it needs measurement data. The function's interface structure includes the array of visuals supported by the system, which is provided by the main program, and the matching array of measurements, which is supplied by the loadable module.

Calibrator Tool calls KCMSCMonMeasure() to "fill in" the measurement data.

Closure

If the loadable module successfully supplies the data measurements, it returns status value 0 (status OK) to Calibrator Tool. Calibrator Tool then calls KCMSCMonClose() to allow the loadable module to free any resources it is using, for example, to unlock the serial port and to close the associated file descriptor.

If, however, the status value returned is any other nonzero value, Calibrator Tool disregards all previously obtained data and informs the end user that calibration has not properly completed. In this case, the calibration process must be restarted from the very beginning with another call to the loadable module.