Class: TImage

Declaration: GraphicImage.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

TModifiableImage

Purpose:

TImage is an abstract base class derived from MGraphic. MGraphic provides the protocols for constructing and deleting a 2-D graphic, obtaining attribute information, transforming the graphic, finding the bounds of the graphic, and hit detection. TImage provides a wrapper for the TGImage geometry class, to which it adds the facilities inherited from MGraphic. TGImage is a device-independent, pixel-based geometry. TImage's attribute bundle holds image filtering attributes. To really understand images, you must understand three spaces: (1) modeling space: the infinite, virtual, coordinate system in which the TImage appears. Most operations are in modeling space; (2) image space or world space: the coordinate system of the rendering device, or the view on the rendering device in which the image appears; and (3) pixel space: the device-independent space of the source image where incrementing by 1 moves to the next pixel. In addition to the standard Draw call, TImage also has a DrawPartial member function. DrawPartial only draws the portion of the image that lies within the specified rectangle, clipping the portion(s) of the image that fall outside the specified rectangle.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Provided classes include TModifiableImage, itself an abstract base class. Deriving classes must override the member function Draw(), DrawPartial(), GetMatrix() etc.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TImage::~TImage

virtual ~ TImage ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::GetMatrix

virtual const TGrafMatrix * GetMatrix () const

Interface Category:

API.

Purpose:

Returns the transformation matrix of the image in world space.

Calling Context:

Call to determine the image's transformation matrix.

Parameters:

Takes no parameters.

Return Value:

Returns the transformation matrix of the image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::GetImage

virtual const TGImage * GetImage () const

Interface Category:

API.

Purpose:

Returns the image geometry for which this class is a wrapper. The returned image geometry is uneditable.

Calling Context:

Call to get a pointer to the image geometry.

Parameters:

Takes no parameters.

Return Value:

Returns a TGimage representing the image geometry of this image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort * port =NIL) const

Interface Category:

API.

Purpose:

Calculates and returns the image's bounding rectangle, including any area determined by the attribute bundle.

Calling Context:

Call to determine the size of the rectangle enclosing the image.

Parameters:

const TGrafPort * port =NIL -The grafport whose bounding rectangle is to be computed.

Return Value:

Returns the smallest rectangle that fully encloses the image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Calculates and returns the image's bounding rectangle, not including any area determined by the attribute bundle.

Calling Context:

Call to determine the size of the rectangle enclosing the image.

Parameters:

Takes no parameters.

Return Value:

Returns the smallest rectangle that fully encloses the image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::GetSourceBounds

virtual TGRect GetSourceBounds () const

Interface Category:

API.

Purpose:

Calculates and returns the bounding rectangle of the source image for the image object (in pixel space).

Calling Context:

Call to determine the bounds of the source image.

Parameters:

Takes no parameters.

Return Value:

Returns the smallest rectangle that fully encloses the source image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the graphic to the specified TGrafPort. TImage also implements DrawPartial to render rectangular portions of the image.

Calling Context:

Call to render the image to the port.

Parameters:

TGrafPort & port -The port into which to render the image.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::DrawPartial

virtual void DrawPartial (TGrafPort & port, const TGRect & areaOfInterestInSource) const

Interface Category:

API.

Purpose:

Draws the portion of the image that lies within the specified rectangle to the specified TGrafPort.

Calling Context:

Call to render a rectangular portion of the image.

Parameters:

TGrafPort & port -The port into which to render the image.
const TGRect & areaOfInterestInSource -The rectangular portion of the image to render.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the image's shape and position by concatenating the specified transformation matrix to the current transformation matrix.

Calling Context:

Call to transform the image.

Parameters:

const TGrafMatrix & -The matrix specifying the transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::ScaleBy

virtual void ScaleBy (const TGPoint &, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Changes the image's size according to the specified horizontal and vertical scalars, centering the object at the specified point. Scaling is applied to the current transformation matrix.

Calling Context:

Call to scale the image.

Parameters:

const TGPoint & scale -The x-coordinate of scale indicates the horizontal scaling factor. The y-coordinate of scale indicates the vertical scaling factor.
const TGPoint & center =TGPoint :: kOrigin -The location at which to center the image.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the image's position according to the specified vector.

Calling Context:

Call to move the image to a new location.

Parameters:

const TGPoint & delta -The x-coordinate of delta indicates the amount by which to move the image horizontally. The y-coordinate of delta indicates the amount by which to move the image vertically.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::RotateBy

virtual void RotateBy (GDegrees, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Rotates the image clockwise by the specified number of degrees about the specified center. Rotation is applied to the current transformation matrix.

Calling Context:

Call to rotate the image.

Parameters:

GDegrees degrees -The number of degrees to rotate the image. Negative degrees indicate that the image should be rotated counterclockwise.
const TGPoint & =TGPoint :: kOrigin -The point in the image about which to rotate the image.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::CreateTransformedCopy

virtual TImage * CreateTransformedCopy (const TGrafMatrix * overTransformer =NIL) const

Interface Category:

API.

Purpose:

Creates a duplicate of the image with the pixels transformed according to the specified transformation matrix. It does not alter the image matrix or the dpi. The overtransform is in world space. CreateTransformedCopy allows you to zoom in or out on an image and still have the same resolution. Calling CreateTransformedCopy with a uniform scale by 2 doubles the number of pixels along the length and width of the image. The filter for the image transformation is in the bundle. This function is currently not implemented.

Calling Context:

Call to create a transformed copy of the image.

Parameters:

const TGrafMatrix * overTransformer =NIL -The transformation matrix with which to transform the copy. The default value is NIL.

Return Value:

Returns a pointer to the newly created copy of the image.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::TImage

TImage ()
TImage (const TGrafMatrix &, TGrafBundle * adoptBundle =NIL)
TImage (const TImage &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a TImage initialized with the transformation matrix and the attribute bundle specified.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Call to create a TImage initialized with a transformation matrix and attribute bundle.
Called to copy an object.

Parameters:

Takes no parameters.
const TGrafMatrix & -The initial transformation matrix for the image. The default is the identity matrix.
TGrafBundle * adoptBundle =NIL -The initial attribute bundle for the image. The default is NIL.
const TImage & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TImage is an abstract base class. Do not instantiate.

Member Function: TImage::operator=

TImage & operator =(const TImage & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TImage & source -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TImage::Validate

void Validate ()

Interface Category:

API.

Purpose:

fBounds validation method.

Calling Context:

Called to validate the TImage.fBounds instance variable.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.