Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
TGModifiableImage
TVideoImage
Purpose:
TGImage derives from MCollectible and is a device-independent, uneditable, pixel-based geometry. Use TGImage and its derived classes to store and manipulate images described in terms of pixel values. TGImage supports devices with nonsquare pixels by allowing you to specify different vertical and horizontal resolutions. TGImage supports the notion of an active area that is the area of the image to be drawn. The boundary of the active area is known as the raster bounds.
Classes deriving from TGImage provide for modifiable images as well as implementing various pixel buffer storage formats.
Instantiation:
Abstract base class; do not allocate.
Deriving Classes:
Classes derived from TGImage must override several pure virtual functions: GetPixel, GetPixelLayout, GetPixelLayoutHash, GetChannelAddress, GetRowStride, GetColumnStride and CreateNativePixelReader. Classes that derive from TGImage and that contain a pyramid of or multiple scaled versions of the image should override ContainsMultiResolutions to return true.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TGImage ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetRasterBounds
TLongRect GetRasterBounds () const
Interface Category:
API.
Purpose:
Returns the raster bounds (the rectangle defining the active area) of the image. The active area of the image is the portion of the entire image drawn when the image is asked to render itself.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TLongRect containing the raster bounds for the image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetResolution
TGPoint GetResolution () const
Interface Category:
API.
Purpose:
Returns the horizontal and vertical resolution of the image. The image resolution is measured in dots per inch.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TGPoint whose x-coordinate represents the horizontal resolution of this image, and whose y-coordinate represents the vertical resolution of this image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetOrientation
EOrientation GetOrientation () const
Interface Category:
API.
Purpose:
Returns the rotation and reflection of the image. An image can be rotated 0, 90, 180, or 270 degrees. In addition, an image can also be reflected about its vertical axis.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns an EOrientation--an enumerated type defined by this class--which indicates both the rotation and the reflection of the image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetColorProfile
const TColorProfile * GetColorProfile () const
Interface Category:
API.
Purpose:
Returns the color profile to use for color matching. Color profiles are required by all devices that intend to do color matching.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a const pointer to a TColorProfile object representing the color profile for this image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetSeed
TPseudoTimeStamp GetSeed () const
Interface Category:
API.
Purpose:
Returns the unique number identifying this image. The seed is updated automatically when the image's attributes change. You can use the seed to determine if redrawing the image is necessary or if caches need updating.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TPseudoTimeStamp object uniquely identifying this image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetTileSize
virtual TGPoint GetTileSize () const
Interface Category:
API.
Purpose:
Gets the width and height of the tiles used to dice up the original image. Tiles can be image-sized or smaller. The default case is that only one tile exists and it is large enough to encompass the entire image. Quite often large images are diced up into tiles to improve the locality of reference.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TGPoint whose x-coordinate represents the width of the tiles, and whose y-coordinate represents the height of the tiles.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetColorTable
virtual const TColorTable * GetColorTable () const
Interface Category:
API.
Purpose:
Returns a const pointer to a TColorTable if the pixel values represent an index into a color table. TGImage's implementation of GetColorTable returns NIL. You can derive from TGImage and override GetColorTable for different behavior.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a const point to a TColorTable object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::ContainsMultiResolutions
virtual bool ContainsMultiResolutions () const
Interface Category:
API.
Purpose:
Determines whether the TGImage contains a pyramid of, or multiple scaled versions of, the image. TGImage's implementation of ContainsMultiResolutions returns false. You can derive from TGImage and override ContainsMultiResolutions for different behavior.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the TGImage contains a pyramid of, or multiple scaled versions of, the image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::SetColorProfile
virtual void SetColorProfile (const TColorProfile &)
Interface Category:
API.
Purpose:
Sets the color profile to use for color matching for this image. This function deletes the previous color profile object and updates the image's seed.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::SetResolution
virtual void SetResolution (TGPoint dpi)
Interface Category:
API.
Purpose:
Sets the horizontal and vertical resolutions of the image. The input parameter to SetResolution is a TGPoint whose x-coordinate represents the horizontal resolution and whose y-coordinate represents the vertical resolution of the image. Resolution is measured in dots per inch. This function also updates the image's seed.
Calling Context:
Call this function directly.
Parameters:
- TGPoint dpi -The new horizontal and vertical resolutions for this image.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::SetOrientation
virtual void SetOrientation (EOrientation orientation)
Interface Category:
API.
Purpose:
Sets the rotation and reflection of the image. This function requires an input parameter of the enumerated type EOrientation defined by this class. SetOrientation updates the image's seed.
Calling Context:
Call this function directly.
Parameters:
- EOrientation orientation -The new reflection and rotation for this image.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetPixel
virtual void GetPixel (long xLocation, long yLocation, TColor & color) const
Interface Category:
API.
Purpose:
Places the color of the pixel at the specified location into the TColor object provided as a parameter. The location is specified in the image's coordinate system.
Calling Context:
Call this function directly.
Parameters:
- long xLocation -The x-coordinate of the pixel location.
- long yLocation -The y-coordinate of the pixel location.
- TColor & color -The color of the pixel at the specified location.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::GetPixelLayout
virtual void GetPixelLayout (TPixelLayout & specs) const
Interface Category:
API.
Purpose:
Initializes the TPixelLayout parameter with a pixel buffer channel and format values, plus a hash value.
Calling Context:
Call this function directly.
Parameters:
- TPixelLayout & specs -The new pixel layout specification for this image.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::GetPixelLayoutHash
virtual unsigned long GetPixelLayoutHash () const
Interface Category:
API.
Purpose:
Gets the hash value calculated in the call to GetPixelLayout.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a long integer that is the pixel layout hash.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::CreateNativePixelReader
virtual TPixelStreamReader * CreateNativePixelReader () const
Interface Category:
API.
Purpose:
Creates a pixel reader which can read the storage format native to this image. The caller is responsible for destroying the pixel reader created by this function.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TPixelStreamReader object created.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::CreateA8G8PixelReader
virtual TPixelStreamReader * CreateA8G8PixelReader () const
Interface Category:
API.
Purpose:
Creates a pixel reader that can read the A8G8 storage format. A8G8 means that each pixel is stored as 16 bits: the first 8 bits contain alpha and the second 8 bits contain the gray value for the pixel. This pixel reader can be used to convert an image to grayscale. The caller is responsible for destroying the pixel reader created by this function.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TPixelStreamReader object created.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::CreateA8R8G8B8PixelReader
virtual TPixelStreamReader * CreateA8R8G8B8PixelReader () const
Interface Category:
API.
Purpose:
Creates a pixel reader that can read the A8R8G8B8 storage format. A8R8G8B8 means that each pixel is stored as 32 bits divided into four 8-bit components: alpha, red, green, and blue. The red, green, and blue components form a coordinate in an RGB space. This pixel reader can be used to convert an image to RGB color space. The caller is responsible for destroying the pixel reader created by this function.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TPixelStreamReader object created.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::CreatePixelReader
virtual TPixelStreamReader * CreatePixelReader (const TPixelLayout & destPixelLayout) const
Interface Category:
API.
Purpose:
Creates either an A8G8 or an A8R8G8B8 pixel reader depending on the value specified in the TPixelLayout parameter. The caller is responsible for destroying the pixel reader created by this function.
Calling Context:
Call this function directly.
Parameters:
- const TPixelLayout & destPixelLayout -The pixel layout format that the new pixel reader must be able to read.
Return Value:
Returns a pointer to the TPixelStreamReader object created.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::GetChannelAddress
virtual const void * GetChannelAddress (unsigned long channelNumber) const
Interface Category:
API.
Purpose:
Gets the memory address of the specified channel. The memory is uneditable by the caller. This function returns NIL if the specified channel isn't valid.
Calling Context:
Call this function directly.
Parameters:
- unsigned long channelNumber -The channel number for which the address is requested.
Return Value:
Returns a const pointer to the address at the beginning of the channel.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::GetRowStride
virtual ptrdiff_t GetRowStride (unsigned long channelNumber) const
Interface Category:
API.
Purpose:
Gets the size in bytes between a component and its vertical neighbor for the specified channel number.
Calling Context:
Call this function directly.
Parameters:
- unsigned long channelNumber -The channel number for which the row stride is requested.
Return Value:
Returns a ptrdiff_t indicating the row stride of the channel in bytes.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::GetColumnStride
virtual unsigned long GetColumnStride (unsigned long channelNumber) const
Interface Category:
API.
Purpose:
Gets the size in bits between a component and its horizontal neighbor for the specified channel number.
Calling Context:
Call this function directly.
Parameters:
- unsigned long channelNumber -The channel number for which the column stride is requested.
Return Value:
Returns a ptrdiff_t indicating the column stride of the channel in bits.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TGImage.
Member Function: TGImage::GetRequiredRasterSize
static TGPoint GetRequiredRasterSize (const TGPoint & imageSizeInWorldSpace, const TGPoint & imageResolution, EOrientation imageOrientation =kIdentity)
Interface Category:
API.
Purpose:
Calculates and returns the required width and height, in pixel space, for an image defined in world space. You must provide the image's size in world space, the desired resolution, and the desired orientation of the image to this function. The returned TGPoint contains the height and width, in pixels, required to store the image.
Calling Context:
Call this function directly.
Parameters:
- const TGPoint & imageSizeInWorldSpace -The size of the image measured in the world coordinate system.
- const TGPoint & imageResolution -The desired resolution of the image in pixel space.
- EOrientation imageOrientation =kIdentity -The desired orientation of the image in pixel space.
Return Value:
Returns a TGPoint whose x-coordinate represents the required width and whose y-coordinate represents the required height in pixel space.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::operator>>=
virtual TStream & operator >>=(TStream&) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & towhere -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: TGImage::operator<<=
virtual TStream & operator <<= (TStream&)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromwhere -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.
- TGImage ()
- TGImage (const TLongRect & bounds, TGPoint dpi =TGImage :: k72DPI, EOrientation orientation =kIdentity)
- TGImage (const TGImage &)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a TGImage initialized with the specified parameters.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Call this function directly.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TLongRect & bounds -The bounding rectangle for the new image.
- TGPoint dpi =TGImage :: k72DPI -The horizontal and vertical resolutions for the image. The default value is 72 dots per inch on both axes.
- EOrientation orientation =kIdentity -The orientation of the new image. The default orientation has no rotation or reflection.
- const TGImage & -The object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
TGImage is an abstract base class--all the constructors are protected. Do not instantiate this class.
Member Function: TGImage::UpdateSeed
void UpdateSeed ()
Interface Category:
API.
Purpose:
Bumps the unique number identifying this image. The image's seed is automatically updated via UpdateSeed when the image's attributes change.
Calling Context:
Friend classes or classes deriving from TGImage can call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
UpdateSeed is a protected member function.
Member Function: TGImage::SetRasterBounds
void SetRasterBounds (const TLongRect & bounds)
Interface Category:
API.
Purpose:
Sets the raster bounds of the image. The raster bounds is the bounding rectangle for the active portion of the image.
Calling Context:
Friend classes or classes deriving from TGImage can call this function directly.
Parameters:
- const TLongRect & bounds -The new raster bounds.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
SetRasterBounds is a protected member function.
Member Function: TGImage::operator=
const TGImage & operator =(const TGImage & source)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
- const TGImage & source -The object to be copied.
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The operator =is a protected member function.
Member Function: TGImage::GetImageBounds
static TGRect GetImageBounds (const TGImage & theImage)
Interface Category:
API.
Purpose:
Calculates and returns the boundary, in user space, for the specified image. This is the WYSIWYG bounds.
Calling Context:
Call this function directly.
Parameters:
- const TGImage & theImage -The image for which to calculate the bounding rectangle.
Return Value:
Returns a TGRect containing the bounding rectangle in user space for the specified image.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGImage::CalculateWorldToPixelTransform
static void CalculateWorldToPixelTransform (const TGImage & thePixels, const TGPoint & topLeftCornerInWorld, TGRect & resultingWorldBounds, TGrafMatrix & resultingTransform)
Interface Category:
API.
Purpose:
Calculates the boundary, in user space, for the specified image and calculates an accompanying transform . This is the WYSIWYG bounds.
Calling Context:
Call this function directly.
Parameters:
- const TGImage & thePixels -The image in question
- const TGPoint & topLeftCornerInWorld -the top left corner of the image in WYSIWYG space
- TGRect & resultingWorldBounds -The returned WYSIWYG bounds.
- TGrafMatrix & resultingTransform -The returned WYSIWYG transform.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.