Class Definition File | Trnsform.idl |
Class C++ Binding | Trnsform.xh |
Class Hierarchy |
SOMObject
ODObject
ODBaseTransform
ODTransform
|
Description | An object of the ODTransform class maps points and shapes from one coordinate system to another. This can be viewed as modifying a shape, for example, by scaling or rotating it. A transform uses a 3-by-3 matrix to perform two-dimensional transformations. The simplest transform is an identity transform, which has no effect on any points or shapes that it transforms. Your part creates a new identity transform by calling the CreateTransform method of a frame, the CreateTransform method of facet, or the NewTransform method of an existing transform. Your part can create a copy of an existing transform by calling that transform's Copy method. You can use a transform to perform the following transformations on coordinates or shapes: For more information on matrixes and transformations in two-dimensional drawing, refer to a standard computer-graphics text. You can also refer to the chapter on drawing in the OpenDoc Programming Guide. You do not need to subclass ODTransform; however, you can provide for new transforms by creating subclasses of ODTransform. For example, you can define new transforms that do not use transformation matrixes. These new transforms might perform more complex operations, such as morphing or wrapping around a 3D surface. |
Overriding Inherited Methods | The following methods are inherited and available for use by your subclass of ODTransform. |
Methods | The methods defined by the ODTransform class include: Creating Transforms Applying Transforms Testing Transforms Manipulating Matrixes
Manipulating Translation Values
Manipulating Scaling Factors Initializing |
Overridden Methods | There are no methods overridden by the ODTransform class. |
This method creates a new transform that is a copy of this transform.
Signature
ODTransform *Copy () |
Parameters
None.
Returns
Remarks
The new transform does not share data with this transform. You can modify each of the transforms independently.
This method initializes the reference count of the returned transform. When you have finished using that transform, you should call its Release method.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to copy the transform. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method modifies this transform to make it equivalent to the specified source transform.
Signature
ODTransform *CopyFrom (ODTransform *sourceTransform) |
Parameters
Returns
Remarks
After this method executes successfully, this transform and the source transform do not share data You can modify each of the transforms independently.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method copies this transform's matrix into the specified structure.
Signature
void GetMatrix (ODMatrix *matrix) |
Parameters
Returns
None.
Remarks
If you use transforms of the class ODTransform and you have also created a subclass of ODTransform that applies complex transformation effects that cannot be represented by matrixes, your part needs to check whether a given transform has a matrix before calling this method. To do so, you should call the transform's HasMatrix method; only if that method returns kODTrue should you call the transform's GetMatrix method.
Exception Handling
| kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method must not call its inherited method. Instead, it should raise an kODErrTransformErr exception. You can detect that a transform of your class has no matrix by calling its HasMatrix method.
Related Methods
This method returns a GPI matrix based on the OpenDoc matrix.
Signature
void GetMATRIXLF (MATRIXLF *mtx) |
Parameters
Returns
None.
Remarks
Because GPI matrixes do not support all transformations which may be represented by an OpenDoc transformation matrix, these two matrixes can not represent the same transform.
This method returns this transform's translation values, the offset values in the specified structure.
Signature
void GetOffset (ODPoint *offset) |
Parameters
Returns
None.
Remarks
The returned horizontal and vertical translation values are located in this transform's matrix; they are the first two elements of the bottom row in the matrix.
Related Methods
This method returns this transform's translation values as a platform specific coordinate pair.
Signature
Point GetOffsetAsPoint () |
Parameters
None.
Returns
Remarks
The returned horizontal and vertical translation values are located in the first two elements of the bottom row of the matrix. On Windows, the coordinate pair is returned as a POINT. On AIX, the coordinate pair is returned as an XPOINT.
Related Methods
This method returns, in the specified structure, the offset to use if you are going to apply the offset before scaling.
Signature
void GetPreScaleOffset (ODPoint *offset) |
Parameters
Returns
None.
Remarks
This method is useful if you want to transform your data by first offsetting and then scaling it. It should not be used if the transformation involves rotation, skewing, or perspective.
Related Methods
This method returns this transform's horizontal and vertical scaling factors in the specified structure.
Signature
void GetScale (ODPoint *scale) |
Parameters
Returns
None.
Remarks
Two elements in the transform's matrix specify the amount by which a shape is scaled. The horizontal scaling factor is determined by the element in the top-left corner of the matrix. The vertical scaling factor is governed by element in the center of the matrix.
This method returns the transform type of this transform.
Signature
ODTransformType GetType () |
Parameters
None.
Returns
| kODIdentityXform | Identity transform. |
| kODLinearTranslateXform | Scale, rotate, skew, and translation (offset). |
| kODLinearXform | Scale, rotate and skew. |
| kODPerspectiveXform | Perspective transformation, which applies to 3D or distortion effects. |
| kODScaleTranslateXform | Scale and translation (offset). |
| kODScaleXform | Pure scale. |
| kODTranslateXform | Pure translation (offset). |
This method should indicate whether this transform uses a matrix to describe its transformation.
Signature
ODBoolean HasMatrix () |
Parameters
None.
Returns
| kODTrue | The transform object uses a matrix. |
| kODFalse | The transform object does not use a matrix. |
Remarks
Every objects of the ODTransform class uses a matrix; hence, this method returns kODTrue. However, if you use transforms of the ODTransform class and you also have created a subclass of ODTransform that applies complex transformation effects that cannot be represented by matrixes, you can call this method to test whether a particular transform belongs to a class that uses a transform matrix.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method must not call its inherited method; instead it should return kODFalse.
This method initializes this transform.
Signature
void InitTransform () |
Parameters
None.
Returns
None.
Remarks
This method is not called directly to initialize this transform object, but is called by a subclass-specific initialization method. By convention, every subclass of ODTransform should have a separate initialization method (for example, the InitMyTransform method) that is called when an instance of that subclass is created. The initialization method may have additional parameters beyond those of the InitTransform method. The InitMyTransform method should call the inherited InitTransform method at the beginning of its implementation.
If you subclass ODTransform, your subclass-specified initialization method, rather than its somInit method, should handle any initialization code that can potentially fail. For example, your initialization method may attempt to allocate memory for your transform.
Override Policy
If you subclass ODTransform, you should not override this method.
This method should invert this transform's matrix.
Signature
ODTransform *Invert () |
Parameters
None.
Returns
Remarks
The inverse of a transform is the mathematical inverse of its matrix. It has the exact opposite geometric effect of the original transform.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to invert the matrix. |
| kODErrTransformErr | The transform has no inverse. This is not true of most real-world transformations, only for those that perform transformations such as flattening a shape into a single line or point. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method should modify the location of the specified point by applying the inverse of this transform matrix.
Signature
void InvertPoint (ODPoint *point) |
Parameters
Returns
None.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to compute the inverse matrix. |
| kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods
This method should modify the specified shape by applying the inverse of this transform.
Signature
void InvertShape (ODShape *shape) |
Parameters
Returns
None.
Remarks
This method is operationally equivalent to the InverseTransform method of the specified shape.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to invert the shape. |
| kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods
This method indicates whether this transform's offset elements are integer values.
Signature
ODBoolean IsIntegerOffset () |
Parameters
None.
Returns
| kODTrue | The offset elements are integer values. |
| kODFalse | The offset elements are not integer values. |
Remarks
The translation values are located in the first two elements of the bottom row of the matrix. The translation elements are considered to be integers if their values are within a rounding error (defined as 7/32768 of a fixed integer representation) of an integer.
This method should indicate whether this transform is identical to the specified transform.
Signature
ODBoolean IsSameAs (ODTransform *compareTransform) |
Parameters
Returns
| kODTrue | The transforms are equivalent. |
| kODFalse | The transforms are different. |
Remarks
The transform objects are equal if, and only if, their matrixes are identical (within a rounding error defined to be 7/32 768 units of a fixed integer representation) or if one is an exact multiple of the other.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method offsets this transform's horizontal and vertical translation values by the specified amount.
Signature
ODTransform *MoveBy (ODPoint *point) |
Parameters
Returns
This method creates a new identity transform.
Signature
ODTransform *NewTransform () |
Parameters
None.
Returns
Remarks
This method initializes the reference count of the returned transform. When you have finished using that transform, you should call its Release method.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to create a new transform. |
This method should modify this transform's matrix by postmultiplying it with the specified transform's matrix.
Signature
ODTransform *PostCompose (ODTransform *transform) |
Parameters
Returns
Remarks
Postcomposing multiplies this transform's matrix on the right side by the specified transform:
this <- this x transform
The resulting transform has the same effect as applying the two original transforms in sequence: first this transform, then the other.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method should modify this transform's matrix by premultiplying it with the specified transform's matrix
Signature
ODTransform *PreCompose (ODTransform *transform) |
Parameters
Returns
Remarks
Precomposing multiplies this transform's matrix on the left side by the specified transform.
this <- transform x this
The resulting transform has the same effect as applying the two original transforms in sequence: first the other transform, then this one.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method should read this transform's matrix from the specified storage unit.
Signature
void ReadFrom (ODStorageUnit *storageUnit) |
Parameters
Returns
None.
Remarks
Before calling this method, you must focus the storage unit on the property from which the matrix elements are to be written. The matrix is read from the value of type kODTransform in the focused property. If no such value exists, this transform is reset to an identity transform.
Exception Handling
| kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods
This method should change this transform to the identity transform.
Signature
ODTransform *Reset () |
Parameters
None.
Returns
Remarks
Except for transforms created by the Copy method, newly created transforms start out as identity transforms; this method changes a transform back to the initial state.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
This method scales this transform by the specified vertical and horizontal scaling factors.
Signature
ODTransform *ScaleBy (ODPoint *scale) |
Parameters
Returns
Exception Handling
| kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform. |
Related Methods
This method scales this transform by the reciprocal of the specified vertical and horizontal scaling factors.
Signature
ODTransform *ScaleDownBy (ODPoint *scale) |
Parameters
Returns
Remarks
This method is the inverse of the transform's ScaleBy method.
Related Methods
This method replaces this transform's matrix with the specified matrix.
Signature
ODTransform *SetMatrix (ODMatrix *matrix) |
Parameters
Returns
Remarks
If you specify an identity matrix, the effect of this method is the same as calling the Reset method.
If you use transforms of the ODTransform class and you have also created a subclass of ODTransform that applies complex transformation effects that cannot be represented by matrixes, your part needs to check whether a given transform has a matrix before calling this method. To do so, you should call the transform's HasMatrix method; only if that method returns kODTrue should you call the transform's SetMatrix method.
Exception Handling
| kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method must not call its inherited method; instead, it should raise an kODErrTransformErr exception. You can detect that a transform of your class has no matrix by calling its HasMatrix method.
Related Methods
This method sets the matrix to be identical to the specified GPI matrix.
Signature
void SetMATRIXLF (MATRIXLF *mtx) |
Parameters
Returns
None.
Remarks
The translation component of the MATRIXLF structure is converted to a 16:16 fixed integer representation by shifting the values 16 bits to the left. No checking is done for overflow.
After this method executes successfully, you are responsible for deleting the MATRIXLF structure. This transform does not use or modify it.
This method changes this transform into a pure offset with the specified horizontal and vertical translation values.
Signature
ODTransform *SetOffset (ODPoint *point) |
Parameters
Returns
Remarks
The translation values are the first two elements of the bottom row of a transform's matrix.
Related Methods
This method changes this transform into a pure offset using a platform specific coordinate pair.
Signature
ODTransform SetOffsetUsingPoint (ODPoint *point) |
Parameters
Returns
Remarks
The translation values are the first two elements of the bottom row of the matrix. On Windows, the coordinate pair is a reference to a POINT. On AIX, the coordinate pair is a reference to an XPOINT.
Related Methods
This method should modify the location of the specified point by applying this transform.
Signature
void TransformPoint (ODPoint *point) |
Parameters
Returns
None.
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods
This method transforms an array of points.
Signature
void TransformPoints (ODByteArray *points,
ODULong npoints)
|
Parameters
Returns
None.
Remarks
The points in the array are transformed in-place.
This method modifies the specified shape by applying this transform.
Signature
void TransformShape (ODShape *shape) |
Parameters
Returns
None.
Remarks
Calling this method is equivalent to calling the Transform method of the specified shape.
Exception Handling
| kODErrOutOfMemory | There is not enough memory to transform the shape. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods
This method writes this transform's matrix to the specified storage unit.
Signature
void WriteTo (ODStorageUnit *storageUnit) |
Parameters
Returns
None.
Remarks
Before calling this method, you must focus the storage unit to the property where the matrix is to be written. The matrix writes the matrix into the value of type kODTransform in the focused property, replacing any matrix that was previously stored in that value or creating the value if it does not already exist.
Exception Handling
| kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value. |
Override Policy
If you subclass ODTransform to create a nonlinear transform class, you must override this method. Your override method can call its inherited method at any point in your implementation.
Related Methods