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.