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.
The KcsProfile class provides the following protected members.
Table 5-1 KcsProfile Protected 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). (SeeTable 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. |
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 |
|
---|---|---|
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 |
The following code sample shows you how to interface with the KcsProfile class and its derivatives using the KcsGetAttribute() KCMS framework API wrapper function.
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.
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); } |