KCMS CMM Reference Manual

Chapter 5 `KcsProfile` Class

This chapter describes the primary KcsProfile class. This base class provides basic functionality for using and creating color profiles. It was used to create the KCMS framework API.

As you read this chapter, you will find it helpful to have access to the following header files:

kcsprofi.h
kcspfmt.h and kcsxform.h
kcsattr.h, kcsio.h, and icc.h

The header file for the class is kcsprofi.h. The constant and #define identifiers for this class are defined in the kcsids.h header file as:

const KcsId KcsLoadProfId = {(0x50726F66UL)}; /* 'Prof' */
#define KcsLoadProfIdd (0x50726F66UL) /* 'Prof' */

The protected and public members are described, as well as the member function override rules when deriving from this class.

Protected Members

The KcsProfile class provides the following protected members.

Table 5-1 KcsProfile Protected Members


Protected Member	Description
KcsProfileFormat *iFormat;	Pointer to a `KcsProfileFormat` instance.
KcsOperationType *iOpAndCont;	Indicates which operations and content types are supported by the profile. The profile can support the logical `OR` of any combination of these flags.
virtual KcsStatus createEmptyProfile();	Fill in the minimum amount of data such that when saved and reloaded, no `KcsXform` instances, and only the minimal tags are needed to load it.
void initDataMembers(void);	Sets all member data to a known state. Allows each constructor to initialize all data members to the empty or initial state.
static long isColorSenseCMM(KcsId);	Do not use this method in new CMMs. It is documented for historic reasons (for existing CMM only).
KcsProfile(KcsStatus aStat, KcsIO aIO);	Constructs a `KcsProfile` based on the static store defined by `aIO`.
KcsProfile(KcsStatus *aStat, KcsId aCmmId, KcsVersion aCmmVersion, KcsId aProfId, KcsVersion aProfVersion);	Constructs a `KcsProfile` of the type `aCmmId` with the version `aCmmVersion` using a profile format determined by `aProfVersion`.
KcsStatus setTimeAttribute( KcsAttributeName aAttrName);	Sets attribute specified by `aAttrName` to current time.
virtual KcsStatus updateMonitorXforms( KcsCharacterizationData aChar, KcsCalibrationData aCal, void *CMMSpecificData, KcsCallbackFunction aCallback);	Updates the monitor transformations based on `aChar` and `aCal` using the CMM's techniques. Returns either `KCS_CALIBRATION_UNSUPPORTED` or `KCS_CHARACTERIZATION_UNSUPPORTED`, unless overridden. Some derivatives require specific data in `CMMSpecificData`. All CMMs do a generic update if `CMMSpecificData` is set to `NULL`. Some CMMs callback into `aCallback` if set to non `NULL`.
virtual KcsStatus updatePrinterXforms( KcsCharacterizationData aChar, KcsCalibrationData aCal, void *CMMSpecificData, KcsCallbackFunction aCallback);	Updates the printer transformations based on `aChar` and `aCal` using the CMM's techniques. Returns either `KCS_CALIBRATION_UNSUPPORTED` or `KCS_CHARACTERIZATION_UNSUPPORTED`, unless overridden. Some derivatives require specific data in `CMMSpecificData`. All CMMs do a generic update if `CMMSpecificData` is set to `NULL`. Some CMMs callback into aCallback if set to non `NULL`. Note that this function currently is not supported in the KCMS default CMM.
virtual KcsStatus updateScannerXforms( KcsCharacterizationData aChar, KcsCalibrationData aCal, void *CMMSpecificData, KcsCallbackFunction aCallback);	Updates the scanner transformations based on `aChar` and `aCal` using the CMM's technique. Returns either `KCS_CALIBRATION_UNSUPPORTED` or `KCS_CHARACTERIZATION_UNSUPPORTED`, unless overridden. Most scanners need both aCal and aChar set to generate valid transforms. Some derivatives require specific data in `CMMSpecificData`. All CMMs update if `CMMSpecificData` is set to `NULL`. Some CMMs callback into aCallback if set to non `NULL`.

Public Members

The KcsProfile class provides the following public members.

Table 5-2 KcsProfile Public Members


Public Member	Description
virtual KcsStatus connect(const long count, KcsProfile sequence, const KcsOperationType opAndHints, KcsProfile result, long *failingProfileIndex);	Connects the list of `KcsProfile`'s pointers passed in by the caller via the `sequence` parameter. Returns the new KcsProfile object `result` based on that list. `failingProfileIndex` indicates the number of the profile in the input list that failed. If element `0` in the array caused the connection to fail, `1` is returned.
static KcsProfile * createProfile(KcsStatus aStat, aIO aIO);	Constructs the correct runtime-loadable or internal `KcsProfile` based on the static store defined by `aIO`.
static KcsProfile * createProfile(KcsStatus *Stat, KcsId aCmmId = KcsProfKCMSId, KcsVersion aCmmVersion = KcsProfKCMSVersionId, KcsId aProfId = Kcs2Id(icMagicNumber), KcsVersion aProfVersion = Kcs2Id(icVersionNumber);	Constructs the correct runtime-loadable or internal `KcsProfile` of `aCmmId` type with the `aCmmVersion` version using a `aProfVersion` profile format.
virtual KcsStatus evaluate(const KcsOperationType opAndHints, KcsPixelLayout source, KcsPixelLayout dest, KcsCallbackFunction progress);	Transforms the caller's data. Use `opAndHints` to indicate which transform and content type your `CMM is providing.
virtual KcsStatus getAttribute(KcsAttributeName aName, KcsAttributeValue *aValue);	Sets `aValue` to the attribute's `aName` value.
virtual KcsStatus getAttribute(KcsAttributeName aName, void *data);	Sets `aData` to the attribute's `aName` value.
virtual KcsProfileFormat * getFormat();	Gets the profile format.
virtual KcsOperationType getOpandCont() {return(iOpAndCont);};	Returns the supported operations and content hints.
virtual KcsXform * getXform(KcsStatus *status, const KcsXformType XfType);	Returns the transform of the `XfType` type.
virtual KcsStatus isLoadable();	Returns `KCS_SUCCESS` if meets all loadability requirements.
KcsProfile(KcsStatus *aStat);	Constructor.
virtual ~KcsProfile(void);	Destructor. Frees up accumulated memory by calling all member object's destructors (with `delete()`).
virtual KcsStatus optimize(const KcsOptimizationType type, KcsCallbackFunction progress);	Makes profile as fast and small as possible. Specify optimization for speed or accuracy with the `type` parameter.
virtual KcsStatus propagateAttributes2Xforms();	Propagates all the expected attributes from the profile attribute set to the attribute sets of the transforms.
KcsStatus save(KcsIO *);	Saves to the static store indicated by `aIO`.
virtual KcsStatus setAttribute(KcsAttributeName aName, KcsAttributeType aType, const char *aValue);	Sets the value of `aName` to `aValue`. `aValue` is interpreted as the type `aType`.
virtual KcsStatus setAttribute(KcsAttributeName aName, const KcsAttributeValue *aValue);	Sets the value of `aName` to `aValue`. `aValue` is interpreted as the default type of `aName`.
virtual KcsStatus setAttribute(KcsAttributeName aName, void *data);	Sets the value of `aName` to `data` interpreted as the default type of `aName`.
virtual KcsStatus setOpAndCont(KcsOperationType aOpAndCont);	Sets the support operations and content hints to `aOpAndCont`.
virtual KcsStatus setXform(KcsXformType aXformId, KcsXform *aXform);	Sets the `aXformId` to `aXform`. If the transform is `null`, removes attachment to that particular `KcsXform` instance, if one exists. Directly implemented by calling `KcsProfileFormat::setObject()`.
virtual KcsStatus updateXforms( KcsCharacterizationData aChar, KcsCalibrationData aCal, void *aCMMSpecificData = NULL, KcsCallbackFunction aCallback = NULL);	Takes all data supplied and information contained within its `KcsAttributeSet` instance to determine which type of device to update. Passes `aChar`, `aCal`, `aCMMSpecificData` and `aCallback` to the appropriate `update()DeviceXforms()` call (where `Device` is `Scanner`\|`Monitor`\|`Printer`). (See Table 5-1 for descriptions of these protected members.)
long xformIsNOP(const KcsXformType);	Indicates whether the `KcsXformType` acts on the data passed to it. If no xform is available, returns `true`.

Member Function Override Rules

The following table tells you which KcsProfile member functions you must override and can override when deriving from this class. The member functions indicated with an "X" in the Must column are required to derive successfully from this base class. Others may be used but not overridden.

Table 5-3 KcsProfile Member Function Override Rules


Member Function	Override Rules
Member Function	Must	Can
`connect()`		X
`createEmptyProfile()`		X
`evaluate()`		X
`getAttribute()`		X
`initDataMember()`		X
`isColorSenseCMM()`		X
`KcsProfile()`	X
`~KcsProfile()`		X
`load()`		X
`optimize()`		X
`propagateAttributes2Xforms()`		X
`save()`		X
`setAttribute()`		X
`setOpAndCont()`		X
`setTimeAttribute()`		X
`setXform()`		X
`unload()`		X
`updateMonitorXforms()`		X
`updatePrinterXforms()`		X
`updateScannerXforms()`		X
`updateXforms()`		X
`XformIsNOP()`		X

Examples

The following code sample shows you how to interface with the KcsProfile class and its derivatives using the KcsGetAttribute() KCMS framework API wrapper function.

Example 5-1 `KcsProfile` Class and `KcsGetAttribute()`

KcsStatusId
 KcsGetAttribute(KcsProfileId profile, KcsAttributeName name,
 			KcsAttributeValue *value)
 {
 	VirtualWorld vWorld(true, true);
 	KcsProfile * *profiles = 0;

 	if (gProfileArray == NULL)
 	// no profiles have been loaded or user has not handled a load
 	// error correctly
 	return(KCS_BAD_PROFILE_ID);
 	KcsStatusId stat;
 	profiles = (KcsProfile * *)KcsLockHandle(gProfileArray);
 	if (isValid(profile, profiles))
 		stat = profiles[profile]->getAttribute(name, value);
 	else
 		stat = KCS_BAD_PROFILE_ID;
 	KcsUnlockHandle(gProfileArray);
 	return(stat);
 }

The following code sample shows you how to interface with the KcsProfile class and its derivatives using the KcsConnectProfiles() KCMS framework API wrapper function.

Example 5-2 `KcsProfile` Class and `KcsConnectProfiles()`

KcsStatusId
 KcsConnectProfiles(KcsProfileId *resultProfileId,
 			unsigned long profileCount, KcsProfileId *profileSequence,
 			KcsOperationType operationLoadSet,
 			unsigned long *failedProfileIndex)
 {
 	VirtualWorld vWorld(true, true);
 	KcsProfile * *profiles = 0;
 	KcsStatus result;
 	long i;

 	if (gProfileArray == NULL)
 			// no profiles have been loaded or user hasn't handled a load
 			// error correctly
 			return(KCS_BAD_PROFILE_ID);

 	result = getNewValidIndex(resultProfileId);
 	if (result != KCS_SUCCESS)
 			return(result);
 	profiles = (KcsProfile * *)KcsLockHandle(gProfileArray);
 	KcsMemoryBlock * memblk = new KcsMemoryBlock(&result,
 			sizeof(KcsProfile * ), profileCount);
 	if (memblk == NULL)
 			return(KCS_MEM_ALLOC_ERROR);
 	KcsProfile * *moreProfiles = (KcsProfile * *)memblk->lock();
 	KcsProfile * madeProfile = NULL;
 	long failingNum = 0;
 	for (i = 0; i < profileCount; i++) (
 			if (!isValid(profileSequence[i], profiles)) {
 				*failedProfileIndex = i;
 				*resultProfileId = BAD_PROFILE_ID;
 				memblk->unlock();
 				memblk->dettach();
 				KcsUnlockHandle(gProfileArray);
 				// also have to do a dettach here !!
 				return(KCS_BAD_PROFILE_ID);
 				}
 			else
 				moreProfiles[i] =
 					(KcsProfile *)profiles[profileSequence[i]]->attach();
 			}
 	result = profiles[profileSequence[0]]->connect(profileCount,
 			moreProfiles, operationLoadSet, madeProfile, &failingNum);
 	*failedProfileIndex = failingNum;
 	if (result == KCS_SUCCESS)
 	profiles[*resultProfileId] = madeProfile;

 	for (i = 0; i < profileCount; i++) {
 			moreProfiles[i]->dettach();
 			}
 	memblk->unlock();
 	memblk->dettach();
 	KcsUnlockHandle(gProfileArray);

 gNumProfilesAllocated++;
 return(result);
 }

Chapter 5 KcsProfile Class