Programming Reference: ODTransform

# Programming Reference

## ODTransform

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:

Perspective | Modifies the positions of points to give a three-dimensional effect.
Rotation | Changes the angle of rotation of a shape, rotating all points around a given point.
Scaling | Changes the size of a shape.
Skewing | Changes the slant applied to a shape.
Translation (offset) | Shifts the position of a shape.

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.

- somInit
- somUninit
- Purge

Methods

The methods defined by the ODTransform class include:

Creating Transforms

- Copy
- NewTransform

Applying Transforms

- InvertPoint
- InvertShape
- TransformPoint
- TransformPoints
- TransformShape

Testing Transforms

- GetType
- HasMatrix
- IsIntegerOffset
- IsSameAs

Manipulating Matrixes

- CopyFrom
- GetMatrix
- GetMATRIXLF (OS/2)
- Invert
- PostCompose
- PreCompose
- ReadFrom
- Reset
- SetMatrix
- SetMATRIXLF (OS/2)
- WriteTo

Manipulating Translation Values

- GetOffset
- GetOffsetAsPoint (AIX, Windows)
- GetPreScaleOffset
- MoveBy
- SetOffset
- SetOffsetUsingPoint (AIX, Windows)

Manipulating Scaling Factors

- GetScale
- ScaleBy
- ScaleDownBy

Initializing

- InitTransform

Overridden Methods | There are no methods overridden by the ODTransform class.

### Copy

This method creates a new transform that is a copy of this transform.

Signature

    ODTransform *Copy ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to the newly created transform.

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.

### CopyFrom

This method modifies this transform to make it equivalent to the specified source transform.

Signature

    ODTransform *CopyFrom (ODTransform *sourceTransform)

Parameters

sourceTransform (ODTransform *) - input

  A reference to the source transform to be copied.

Returns

rv (ODTransform *) - returns

  A reference to this transform modified to be a copy of the specified transform.

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.

### GetMatrix

This method copies this transform's matrix into the specified structure.

Signature

    void GetMatrix (ODMatrix *matrix)

Parameters

matrix (ODMatrix *) - output

  The structure in which the matrix is to be returned.

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

- ODTransform::HasMatrix
- ODTransform::SetMatrix

### GetMATRIXLF (OS/2)

This method returns a GPI matrix based on the OpenDoc matrix.

Signature

    void GetMATRIXLF (MATRIXLF *mtx)

Parameters

mtx (MATRIXLF *) - output

  The GPI matrix-elements structure.

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.

### GetOffset

This method returns this transform's translation values, the offset values in the specified structure.

Signature

    void GetOffset (ODPoint *offset)

Parameters

offset (ODPoint *) - output

  A point specifying the horizontal (x) and vertical (y) translation values of this transform.

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

- ODTransform::GetPreScaleOffset
- ODTransform::SetOffset

### GetOffsetAsPoint (AIX, Windows)

This method returns this transform's translation values as a platform specific coordinate pair.

Signature

    Point GetOffsetAsPoint ()

Parameters

None.

Returns

rv (Point *) - returns

  A reference to a platform specific coordinate pair for this transform's translation values.

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

- ODTransform::GetOffset
- ODTransform::SetOffset
- ODTransform::SetOffsetUsingPoint (AIX, Windows)

### GetPreScaleOffset

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

offset (ODPoint *) - output

  A point specifying the horizontal (x) and vertical (y) translation values to use before scaling.

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

- ODTransform::GetOffset

### GetScale

This method returns this transform's horizontal and vertical scaling factors in the specified structure.

Signature

    void GetScale (ODPoint *scale)

Parameters

scale (ODPoint *) - output

  A point specifying the horizontal (x) and vertical (y) scaling factors.

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.

### GetType

This method returns the transform type of this transform.

Signature

    ODTransformType GetType ()

Parameters

None.

Returns

rv (ODTransformType) - returns

  The transform type of this transform. This parameter can be set to one of the following values:

  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).

### HasMatrix

This method should indicate whether this transform uses a matrix to describe its transformation.

Signature

    ODBoolean HasMatrix ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the transform object uses a matrix.

  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.

### InitTransform

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.

### Invert

This method should invert this transform's matrix.

Signature

    ODTransform *Invert ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to this transform with its matrix changed to represent the inverse of its original matrix.

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.

### InvertPoint

This method should modify the location of the specified point by applying the inverse of this transform matrix.

Signature

    void InvertPoint (ODPoint *point)

Parameters

point (ODPoint *) - in/out

  The point to be modified. On return, the fields of this structure have been modified to represent the modified point.

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

- ODTransform::TransformPoint

### InvertShape

This method should modify the specified shape by applying the inverse of this transform.

Signature

    void InvertShape (ODShape *shape)

Parameters

shape (ODShape *) - input

  A reference to the shape object whose geometric representation is to be modified by the inverse of this transform.

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

- ODShape::InverseTransform

### IsIntegerOffset

This method indicates whether this transform's offset elements are integer values.

Signature

    ODBoolean IsIntegerOffset ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this transform's offset elements are integer values.

  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.

### IsSameAs

This method should indicate whether this transform is identical to the specified transform.

Signature

    ODBoolean IsSameAs (ODTransform *compareTransform)

Parameters

compareTransform (ODTransform *) - input

  A reference to the transform to be used for comparison.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the transforms are equivalent (that is, they describe the same transformation).

  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.

### MoveBy

This method offsets this transform's horizontal and vertical translation values by the specified amount.

Signature

    ODTransform *MoveBy (ODPoint *point)

Parameters

point (ODPoint *) - input

  A point specifying the horizontal (x) and vertical (y) translations to be added to the current translation values.

Returns

rv (ODTransform *) - returns

  A reference to this transform after the offset operation.

### NewTransform

This method creates a new identity transform.

Signature

    ODTransform *NewTransform ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to the newly created transform or kODNULL if an error occurred.

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.

### PostCompose

This method should modify this transform's matrix by postmultiplying it with the specified transform's matrix.

Signature

    ODTransform *PostCompose (ODTransform *transform)

Parameters

transform (ODTransform *) - input

  A reference to the transform whose matrix is to be postmultiplied with this transform's matrix.

Returns

rv (ODTransform *) - returns

  A reference to this transform after the postcompose operation.

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.

### PreCompose

This method should modify this transform's matrix by premultiplying it with the specified transform's matrix

Signature

    ODTransform *PreCompose (ODTransform *transform)

Parameters

transform (ODTransform *) - input

  A reference to the transform whose matrix is to be premultiplied with this transform's matrix.

Returns

rv (ODTransform *) - returns

  A reference to this transform after the precompose operation.

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.

### ReadFrom

This method should read this transform's matrix from the specified storage unit.

Signature

    void ReadFrom (ODStorageUnit *storageUnit)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the storage unit from which the matrix is to be read.

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

- ODTransform::WriteTo

### Reset

This method should change this transform to the identity transform.

Signature

    ODTransform *Reset ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to this transform reset to the identity transform.

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.

### ScaleBy

This method scales this transform by the specified vertical and horizontal scaling factors.

Signature

    ODTransform *ScaleBy (ODPoint *scale)

Parameters

scale (ODPoint *) - input

  A point specifying the horizontal (x) and vertical (y) scaling factors.

Returns

rv (ODTransform *) - returns

  A reference to this transform after the scaling operation.

Exception Handling

kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform.

Related Methods

- ODTransform::ScaleDownBy

### ScaleDownBy

This method scales this transform by the reciprocal of the specified vertical and horizontal scaling factors.

Signature

    ODTransform *ScaleDownBy (ODPoint *scale)

Parameters

scale (ODPoint *) - input

  A point specifying the horizontal (x) and vertical (y) scaling factors.

Returns

rv (ODTransform *) - returns

  A reference to this transform after the scaling operation.

Remarks

This method is the inverse of the transform's ScaleBy method.

Related Methods

- ODTransform::ScaleBy

### SetMatrix

This method replaces this transform's matrix with the specified matrix.

Signature

    ODTransform *SetMatrix (ODMatrix *matrix)

Parameters

matrix (ODMatrix *) - input

  The new transform matrix for this transform.

Returns

rv (ODTransform *) - returns

  A reference to this transform with its matrix replaced.

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

- ODTransform::GetMatrix
- ODTransform::HasMatrix
- ODTransform::Reset

### SetMATRIXLF (OS/2)

This method sets the matrix to be identical to the specified GPI matrix.

Signature

    void SetMATRIXLF (MATRIXLF *mtx)

Parameters

mtx (MATRIXLF *) - input

  The GPI matrix-elements structure.

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.

### SetOffset

This method changes this transform into a pure offset with the specified horizontal and vertical translation values.

Signature

    ODTransform *SetOffset (ODPoint *point)

Parameters

point (ODPoint *) - input

  A point specifying the new horizontal (x) and vertical (y) translation values.

Returns

rv (ODTransform *) - returns

  A reference to this transform changed to an offset transform.

Remarks

The translation values are the first two elements of the bottom row of a transform's matrix.

Related Methods

- ODTransform::GetOffset

### SetOffsetUsingPoint (AIX, Windows)

This method changes this transform into a pure offset using a platform specific coordinate pair.

Signature

    ODTransform SetOffsetUsingPoint (ODPoint *point)

Parameters

point (ODPoint *) - input

  A point specifying the new horizontal and vertical translation values.

Returns

rv (ODTransform *) - returns

  A reference to this transform changed to an offset transform.

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

- ODTransform::GetOffset
- ODTransform::GetOffsetAsPoint (AIX, Windows)
- ODTransform::SetOffset

### TransformPoint

This method should modify the location of the specified point by applying this transform.

Signature

    void TransformPoint (ODPoint *point)

Parameters

point (ODPoint *) - in/out

  The point to be modified. On return, the fields of this structure have been modified to represent the transformed point.

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

- ODTransform::InvertPoint

### TransformPoints

This method transforms an array of points.

Signature

    void TransformPoints (ODByteArray *points,
                          ODULong npoints)

Parameters

points (ODByteArray *) - in/out

  A pointer a byte array structure referencing an array of ODPoint structures.

npoints (ODULong) - output

  The number of points in the points.

Returns

None.

Remarks

The points in the array are transformed in-place.

### TransformShape

This method modifies the specified shape by applying this transform.

Signature

    void TransformShape (ODShape *shape)

Parameters

shape (ODShape *) - input

  A reference to the shape object to be modified.

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

- ODShape::Transform
- ODTransform::InvertShape

### WriteTo

This method writes this transform's matrix to the specified storage unit.

Signature

    void WriteTo (ODStorageUnit *storageUnit)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the storage unit where this transform's matrix is to be written.

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

- ODTransform::ReadFrom

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]