class HT_Shared

class HT_Shared_Image

This class encapsulates images.

The class appears in the API as arguments to draw_dc_image and draw_2d_image, read_dc_depth_image, and read_dc_color_image.

Encapsulated Type

class HT_Image_Format {
    public:
        enum Enum {
            bitonal,
            index8,
            rgb32,
            depth16,
            depth32,

            any,
            device_specific
            invalid = -1
        };
};

Encapsulates the possible formats for this image.

Details

There are two new image formats, any and device_specific. In case the caller of read_dc_...image merely passes the returned image to draw_dc_..._image and does not interpret the data, the image format can be set to any. This enables a Heidi driver to allocate memory on the graphics board or store the image information in whatever format the driver prefers. In return, the Heidi driver sets the image format to device_specific if the returned value is in the driver specific format and should not be interpreted by the caller.

Access Methods

cmyk32_pixel, depth16_pixel, depth32_pixel, gray8_pixel, 
index8_pixel, rgb32_pixel
                        Format-dependent data pointers.

bitonal_format          Returns the bitonal format.

format                  Gets the format of this image object.

height                  Number of scan lines.

image_data              Gets the address of this image object.

in_bounds               Checks to see if the sub-image is within bounds of the image.

invalidate_cached_data  Invalidates the cached data.

packing_order 	     Returns the packing order.

resolution 		     Returns the resolution value.

row                     Returns a raster.

row_bytes               Bytes per scan line.

set_cached_data         Sets the cached data.

width                   Pixels per scan line.

Operators

operator =              Assigns an image.

operator ==             Compares two images.

operator !=             Compares two images to see if they are not equal.

Constructor/Destructor

HT_Shared_Image         Creates a new HT_Shared_Image and initializes it.

~HT_Shared_Image ()     Destroys an HT_Shared_Image.

HT_Shared_Image::bitonal_format

Purpose

Returns the bitonal format.

Synopsis

HT_Bitonal_Format bitonal_format (void) const

Details

HT_Shared_Image::format

Purpose

Get the format of this image object.

Synopsis

HT_Image_Format format (void) const

Details

Class HT_Shared_Image encapsulates several different kinds of images, both color and depth buffers. This method returns the image format of the object, which tells which kind of image it contains.

The return value has one of the enumerated values defined within this class. Values include the following:

bitonal,
       index8,
       rgb32,
       depth16,
       depth32,
       any,
       device_specific,
          invalid = -1

HT_Shared_Image::height

Purpose

Gets the number of scan lines in this image object.

Synopsis

int height (void)

Details

The actual number of scan lines in this image object is returned.

HT_Shared_Image::HT_Shared_Image

Purpose

The constructor to initialize a new image object.

Synopsis

HEIDI_API HT_Shared_Image () {}
        HEIDI_API HT_Shared_Image (
            int                     width,
            int                     height,
            HT_Image_Format         format,
            int                     alignment,
            void alter *            block,
            HT_Boolean              block_by_reference) alter;

Details

This method allocates storage and initializes a new HT_Shared_Image object according to the supplied data.

width and height are the number of columns and rows of the image.

format is one of the enumerated values of HT_Image_Format.

alignment is the number of bytes the image is packed in.

If block is not null, it is taken to point to a memory location with the pixel data for the new HT_Shared_Image object.

If block is not null and block_by_reference is true, then the data pointer in the new HT_Shared_Image object is set equal to block. If block is not null and block_by_reference is false, then the constructor allocates new storage for the data and copies the data referenced by block to it. If block is null, then the constructor allocates new storage for the image data, initialized to arbitrary values.

HT_Shared_Image::~HT_Shared_Image

Purpose

Destroys an image object.

Synopsis

~HT_Shared_Image();

Details

This releases storage for the image data and deletes an HT_Shared_Image object.

HT_Shared_Image::image_data

Purpose

Gets the address of this image object.

Synopsis

HT_Image_Data const & image_data (void) const

Details

Returns the base class HT_Image_Data. This method, however, is rarely used because the information should be accessed with HT_Shared_Image member functions.

HT_Shared_Image::in_bounds

Purpose

Checks to determine if the image is within the bounds

Synopsis

HT_Boolean     in_bounds (HT_Int_XY const & offset) const

HT_Shared_Image::invalidate_cached_data

Purpose

Invalidates the cached data.

Synopsis

void     invalidate_cached_data()

HT_Shared_Image::packing_order

Purpose

Returns the packing order.

Synopsis

HT_Packing packing_order (void) const

HT_Shared_Image::resolution

Purpose

Returns the resolution value.

Synopsis

int resolution (void) const

HT_Shared_Image::..._pixel

Purpose

Accesses a particular element of an image object.

Synopsis

HT_Gray8 const & gray8_pixel (HT_Int_XY offset) const

HT_Gray8 alter & gray8_pixel (HT_Int_XY offset) alter

HT_Gray8 const & gray8_pixel (int x, int y) const

HT_Gray8 alter & gray8_pixel (int x, int y) alter

HT_Index8 const & index8_pixel (HT_Int_XY offset) const

HT_Index8 alter & index8_pixel (HT_Int_XY offset) alter

HT_Index8 const & index8_pixel (int x, int y) const

HT_Index8 alter & index8_pixel (int x, int y) alter

HT_CMYK32 const & cmyk32_pixel (HT_Int_XY offset) const

HT_CMYK32 alter & cmyk32_pixel (HT_Int_XY offset) alter

HT_CMYK32 const & cmyk32_pixel (int x, int y) const

HT_CMYK32 alter & cmyk32_pixel (int x, int y) alter

HT_Depth16 const & depth16_pixel (HT_Int_XY offset) const

HT_Depth16 alter & depth16_pixel (HT_Int_XY offset) alter

HT_Depth16 const & depth16_pixel (int x, int y) const

HT_Depth16 alter & depth16_pixel (int x, int y) alter

HT_Depth32 const & depth32_pixel (HT_Int_XY offset) const

HT_Depth32 alter & depth32_pixel (HT_Int_XY offset) alter

HT_Depth32 const & depth32_pixel (int x, int y) const

HT_Depth32 alter & depth32_pixel (int x, int y) alter

HT_RGB32 const & rgb32_pixel (HT_Int_XY offset) const

HT_RGB32 alter & rgb32_pixel (HT_Int_XY offset) alter

HT_RGB32 const & rgb32_pixel (int x, int y) const

HT_RGB32 alter & rgb32_pixel (int x, int y) alter

Details

offset.x and offset.y specify, respectively, the column and row in the image of the pixel to be accessed. offset.x should be greater than or equal to zero and less than the width of the image. offset.y should be greater than or equal to zero and less than the height of the image.

The return value is a particular pixel value of the appropriate type. For the first three formats this is a value of a simple type:

typedef unsigned short HT_Depth16;

typedef unsigned long HT_Depth32;

typedef unsigned char HT_Index8;

In the fourth case the return value is an object of the class HT_RGB32.

Each of these methods should be called only for images of the appropriate format.

HT_Shared_Image::..._pixel

Purpose

Accesses a particular element of an image object.

Synopsis

HT_Depth16 *depth16_pixel (HT_Int_XY offset)

HT_Depth32 *depth32_pixel (HT_Int_XY offset)

HT_Index8 *index8_pixel (HT_Int_XY offset)

HT_RGB32 *rgb32_pixel (HT_Int_XY offset)

Details

The return value is a pointer to a particular pixel value of the appropriate type. For the first three formats this is a value of a simple type:

typedef unsigned short HT_Depth16;

typedef unsigned long HT_Depth32;

typedef unsigned char HT_Index8;

In the fourth case the return value is a pointer to an object of the class HT_RGB32.

Each of these methods should be called only for images of the appropriate format.

HT_Shared_Image::row

Purpose

Returns a raster

Synopsis

void const * const & row (int p_row) const

void alter * const & row (int p_row) alter

HT_Shared_Image::row_bytes

Purpose

Gets the number of bytes per scan line in this image object.

Synopsis

int row_bytes (void)

Details

The number of bytes per scan line is not necessarily the number of pixels per scan line times the number of bytes per pixel. This is due to possible address boundary rules for scan lines.

HT_Shared_Image::height

Purpose

Gets the number of scan lines in this image object.

Synopsis

int height (void)

HT_Shared_Image::width

Purpose

Gets the number of pixels per scan line in this image object.

Synopsis

int width (void)

HT_Shared_Image::set_cached_data

Purpose

Sets the cached data.

Synopsis

void set_cached_data (const HT_Cached_Data *cached)