KCMS CMM Reference Manual

Chapter 8 KcsXform Class

This chapter describes the KCMS framework KcsXform class. This base class provides an interface for component transformations of different transformation types; for example, matrix and grid-table based.

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

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

const KcsId KcsLoadXfrmId = {(0x5866726dUL)}; /* 'Xfrm' */
#define KcsLoadXfrmIdd (0x5866726dUL) /* 'Xfrm' */

In addition to the KcsLoadable methods overridden by this class, this class includes methods for component transformations of different transformation types. The protected and public members are described, as well as the member function override rules when deriving from this class.

Enumerations

The KcsXform class has the following enumerations.

Table 8-1 KcsXform Enumerations

Enumeration 

Description 

enum KcsInOut {In, Out};

Enumeration used in getNumComponents() , getComponentDepth(), setNumComponents(), and setComponentDepth().

Protected Members

The KcsXform class has the following protected members.

Table 8-2 KcsXform Enumerations

Enumeration 

Description 

long myChunkId;

Current chunk Id. 

KcsOperationType myOpsAndHints;

Current operations and hints. 

KcsTransformKind myKindOf;

Current transform. 

int callbackInterval;

Rows per callback. 

Public Members

The KcsXform class has the following public members.

Table 8-3 KcsXform Public Members

Public Member 

Description 

int 
areLayoutsCloseEnough(KcsPixelLayout *in1,
 	KcsPixelLayout *in2,
 	KcsPixelLayout *out);

Returns nonzero if the nth pixel in in1 and in2 uses the pixel in out without corrupting the (n+1)th pixel of out, (for example, planar<->chunky fails while chunky<->chunky does not); else returns zero.

int 
areLayoutsEqual(KcsPixelLayout *l1,
 	KcsPixelLayout *l2);

Returns non zero if the pixel layout structs in l1 and l2 are identical (especially the pointers to the data buffers); else returns zero.

virtual KcsStatus compose(KcsXformSeq 
 	*xformSeq, KcsXform **newXform,
 	KcsCallbackFunction progress);

Generates a new Xform from xformSeq supplied. Connects numXforms transforms supplied in a KcsXformSeq and returns a KcsXform in newXform that has the same effect as the list of Xforms in the order supplied. An error in connecting from techs[n] to techs[n+1] is reflected in errors[n]. A NULL KcsXform is returned on error.

virtual KcsStatus
connect(const KcsOperationType opsAndHints,
 	const long numXforms,
 	KcsXform **technologies,
 	KcsXform **newXform,
 	KcsCallbackFunction progress,
 	long *numberThatFailed);

Connects numXforms transforms supplied in technologies and returns a KcsXform that has the same effect as the list of Xforms in the order supplied. If an error is found, it is reported. An error in connecting from techs[n] to techs[n+1] is reflected in errors[n]. A NULL KcsXform is returned on error.

virtual KcsStatus
connectSink(KcsPixelLayout *sinkLayout);

Associates sinkLayout as the default layout buffer for output from this transform.

virtual KcsStatus
connectSource(KcsPixelLayout
     *sourceLayout);

Associates sourceLayout as the default layout buffer for input to this transform.

virtual KcsXform 
*convertXform(KcsStatus *aStat,
 	KcsId aXformType);

Converts the instance into a derivative of type aXformType and returns a pointer to the new transform. Does automatic xform conversion when needed.

static KcsXform *
createXform(KcsStatus *status,
 	KcsChunkSet *aChunkSet,
 	KcsChunkId chunkId,
 	KcsAttributeSet *aAttrSet=NULL);

Creates a KcsXform from a chunk set.

KcsStatus eval();

Evaluates the data described in the local inBuffer set by connectSource()through this transform into the buffer described by the outBuffer set by connectSink(). The operation is from myOptType. This provides no progress.

KcsStatus
eval(const KcsOperationType opsAndHints,
 	long *in32, long *out32);

Evaluates the data described in one 32-bit integer. 

KcsStatus 
eval(const KcsOperationType opsAndHints,
 	KcsPixelLayout *inBuffer,
 	KcsPixelLayout *outBuffer,
 	KcsCallbackFunction progress) = 0;

Evaluates the data described in inBuffer through the Xform described by this instance into the buffer described by outBuffer.

KcsStatus 
eval(const KcsOperationType opsAndHints,
 	const float **inComp,
 	const float **outComp,
 	const long *inStride,
 	const long *outStride, const long num,
 	KcsCallbackFunction progress);

Evaluates the data described in the float-based buffer supplied through this transform into the float-based buffer supplied. 

KcsStatus
eval(const KcsOperationType opsAndHints,
 	const unsigned char **inComp,
 	const unsigned char **outComp,
 	const long *inStride,
 	const long *outStride, const long num,
 	KcsCallbackFunction progress);

Evaluates the data described in the byte-based buffer supplied through this transform into the byte-based buffer supplied. 

virtual KcsAttributeSet
 *getAttrSet(KcsStatus *aStat = NULL);

Returns the set of attributes associated with this KcsXform instance. If NULL, creates an empty one.

virtual long
 getComponentDepth(KcsInOut whichOne);

Retrieves the component depth. 

virtual KcsStatus
 getLoadOrder(long aNumTypes,
 	KcsLoadSaveSet aAvailableTypes,
 	KcsLoadSaveSet *aOrderOfTypes);

Given aAvailableTypes, returns the order to load the types in an array aOrderOfTypes[aNumTypes].

virtual long
 getNumComponents(KcsInOut whichOne);

Retrieves the number of components. 

KcsOperationType getOpsAndHints();

Retrieves the ops and hints. 

virtual KcsStatus
 getSaveOrder(long aNumTypes,
 	KcsLoadSaveSet aAvailableTypes,
 	KcsLoadSaveSet *aOrderOfTypes);

Given aAvailableTypes, returns the order to save the types in an array aOrderOfTypes[aNumTypes].

static KcsId
 getXformType(KcsChunkSet *aChunkSet,
 	KcsChunkId chunkId, KcsStatus *stat,
 	int *InComp, int *OutComp);

Gets the Xform type. 

typedef long KcsLoadSaveSet;

Used in getLoadOrder() and getSaveOrder().

typedef unsigned long KcsTransformKind;

Used in kindOfTransform().

KcsXform(KcsStatus *status,
 	KcsAttributeSet *aAttrSet=NULL);

Constructor. 

KcsXform(KcsStatus *status,
 	KcsOperationType opsAndHints,
 	KcsChunkSet *aChunkSet,
 	KcsChunkId chunkId,
 	KcsAttributeSet *aAttrSet=NULL);

Constructor. 

virtual ~KcsXform();

Destructor. 

virtual KcsTransformKind kindOfTransform();

Retrieves the kind of transform. 

virtual KcsStatus
 loadU(KcsMemoryBlock *aXform,
 	KcsCallbackFunction aCallback = NULL);

Loads the Xform from the universal buffer supplied. 

virtual int
 numberOfCallbacks(KcsPixelLayout *aIn,
 	KcsPixelLayout *aOut);

If the Xform evaluated data with the supplied pixel layouts and a callback was supplied, tells how many times the callback would be called. The default is once for every four scan lines of aIn.

KcsStatus optimize();

Optimizes the Xform. 

virtual KcsStatus
 optimize(const KcsOperationType opsAndHints,
 	const KcsOptimizationType optimization,
 	KcsCallbackFunction progress);

Optimizes the Xform. 

virtual KcsStatus
 saveU(KcsMemoryBlock *aXform,
 	KcsCallbackFunction aCallback=NULL);

Saves the Xform into the universal buffer supplied. 

virtual KcsStatus 
setAttrSet(KcsAttributeSet *aAttrSet);

Sets the set of attributes associated with this KcsXform instance.

virtual KcsStatus
 setCallbackInterval(int callbackInt);

Sets the callback interval. 

virtual KcsStatus
 setComponentDepth(KcsInOut whichOne,
 	long Depth = 8);

Sets the component depth. 

virtual KcsStatus setDefaultAttributes(void);

Sets up the default set of attributes for Xforms. 

virtual KcsStatus
 setNumComponents(KcsInOut whichOne,
 	long numComp = 3);

Sets the number of components. 

void setOpsAndHints(KcsOperationType);

Sets the ops and hints. 

KcsStatus
 validateLayouts(
 	KcsPixelLayout *sourceLayout,
 	KcsPixelLayout *sinkLayout);

Makes sure the source layout and sink layout are compatible with each other and with transform. The color space of the buffer is validated once that field is added to the KcsPixelLayout structure.

External Loadable Interface

Use these KcsXform external entry points to load your derivatives at runtime. See the DDK manual KCMS CMM Developer's Guide for more information on creating a KcsXform derivative as a runtime loadable CMM.

Table 8-4 KcsXform External Loadable Interface

Extern "C" 

Description 

extern long KcsDLOpenXfrmCount; 

Holds a counter for the number of times this dynamically loadable module has been loaded. 

KcsStatus KcsInitXfrm(long libMajor,
  	long libMinor, long *myMajor,
  	long *myMinor); 

Returns KCS_SUCCESS.

KcsXfrm  
* KcsCreateXfrm(KcsStatus *aStat,
  	KcsChunkSet *aChunkSet,
  	KcsChunkId aChunkId
,  	KcsAttributeSet *aAttrSet); 

Returns a KcsXform object by invoking the KcsXform constructor.

KcsStatus KcsCleanupXfrm(); 

Returns KCS_SUCCESS.

Member Function Override Rules

The following table tells you which KcsXform 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 can be used and not overridden.

Table 8-5 KcsXform Member Function Override Rules

Member Function 

Override Rules 

Must 

Can 

compose()

 

connect()

 

connectSink()

 

connectSource()

 

connectXform()

 

convertXform()

 

eval()

 

getAttrSet()

 

getLoadOrder()

 

getSaveOrder()

 

KcsXform()

 

~KcsXform()

 

loadU()

 

numberOfCallbacks()

 

optimize()

 

saveU()

 

setAttrSet()

 

setCallbackInterval()

 

setComponentDepth()

 

setDefaultAttributes()

 

setNumComponents()

 

validateLayouts()