Detailed Description

This class provides read-access to the representation of an image in memory.

For the vast majority of image files XSI will represent the data in memory as uncompressed 8-bit RGBA. This is true even if the original file has no alpha information. However, high quality 16-bit and floating point images can also be read via Image::GetPixelArray. You can determine what format the image data contains by means of Image::GetNumChannels and Image::GetChannelSize.

See also:: ImageClip2::GetImage

Since:: 4.0

Example:

Demonstrates how to create an image clip and access information about its underlying image source.

        using namespace XSI;
        Application app ;

        // Create an image clip based on one of the
        // image files from the XSI installation
        CString strImagePath ;
        strImagePath = app.GetInstallationPath( siFactoryPath );
        strImagePath += L"/Data/XSI_SAMPLES/Pictures/upper_eyelash.jpg" ;

        CValueArray args(2);
        CValue retVal;
        args[0] = strImagePath ;
        args[1] = L"MySmallClip" ;

        app.ExecuteCommand( L"CreateImageClip", args, retVal ) ;

        ImageClip2 newClip = retVal ;
        Image myImage = newClip.GetImage() ;

        app.LogMessage( L"Image has resolution " + CValue( myImage.GetResX() ).GetAsText() +
                    L" by " + CValue( myImage.GetResY() ).GetAsText() ) ;

        app.LogMessage( L"Image has " + CValue( myImage.GetNumChannels() ).GetAsText() +
                    L" channels and " + CValue( myImage.GetChannelSize() ).GetAsText() +
                    L" bytes per channel" ) ;

        app.LogMessage( L"Total size of the uncompressed image data is "
                    + CValue( myImage.GetPixelArraySize() / 1024l ).GetAsText()
                    + L" kb" ) ;

        // Get the pixel value at (45, 25)
        unsigned char aColor[4] ;
        myImage.GetPixelValue( 45.0, 25.0, aColor[0], aColor[1], aColor[2], aColor[3] ) ;

        // Alternatively we can use the CColor object, which holds the color as
        // normalized doubles
        CColor myColor ;
        myImage.GetPixelValue( 45.0, 25.0, myColor ) ;

        // Expect results of running this example:
        // INFO : "Image has resolution 875 by 300"
        // INFO : "Image has 4 channels and 1 bytes per channel"
        // INFO : "Total size of the uncompressed image data is 1025 kb"

#include <xsi_image.h>

Inheritance diagram for Image:

[legend]

List of all members.

Public Member Functions
	Image ()
	~Image ()
	Image (const CRef &in_ref)
	Image (const Image &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Image &	operator= (const Image &in_obj)
Image &	operator= (const CRef &in_ref)
CStatus	GetPixelValue (float in_X, float in_Y, CColor &out_Pixels) const
CStatus	GetPixelValue (float in_X, float in_Y, unsigned char &out_R, unsigned char &out_G, unsigned char &out_B, unsigned char &out_A) const
LONG	GetResX () const
LONG	GetResY () const
LONG	GetNumChannels () const
LONG	GetChannelSize () const
const void *	GetPixelArray () const
LONG	GetPixelArraySize () const

Constructor & Destructor Documentation

Image ( )

Default constructor.

~Image ( )

Default destructor.

Image ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Image ( const Image & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Implements CBase.

Image& operator= ( const Image & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Image object.

Image& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Image object.

CStatus GetPixelValue	(	float	in_X,
		float	in_Y,
		CColor &	out_Pixels
	)		const

Reads the color value at a specified pixel value in the image. When in_X or in_Y are not whole numbers Bilinear interpolation is used to determine a subpixel value. The bottom left of the image is considered pixel 0,0.

Parameters:

in_X	X coordinate on the image.
in_Y	Y coordinate on the image.

Return values:

out_Pixels The color of the image at the given coordinate

CStatus GetPixelValue	(	float	in_X,
		float	in_Y,
		unsigned char &	out_R,
		unsigned char &	out_G,
		unsigned char &	out_B,
		unsigned char &	out_A
	)		const

Alternative signature of GetPixelValue which retrieves the color of the pixel as 4 RGBA bytes.

Currently this function only works for 8-bit RGBA images. For other image formats it is possible to read pixel values by calling Image::GetPixelArray.

Parameters:

in_X	X coordinate on the image.
in_Y	Y coordinate on the image.

Return values:

out_R	The red component value of the color of the image at the given coordinate
out_G	The green component value of the color of the image at the given coordinate
out_B	The blue component value of the color of the image at the given coordinate
out_A	The alpha component value of the color of the image at the given coordinate

LONG GetResX ( ) const

Returns the resolution, in pixels, of the horizontal dimension.

LONG GetResY ( ) const

Returns the resolution, in pixels, of the vertical dimension.

LONG GetNumChannels ( ) const

Returns the number of channels per pixel. Normally this returns 4, representing RGBA. XSI will often represent an image in memory with 4 channels even if the underlying file format has no alpha information.

LONG GetChannelSize ( ) const

Returns the number of bytes per channel. Normally this returns 1, but 16-bit images will return 2 and 32-bit float images will return 4.

const void* GetPixelArray ( ) const

Provides low level access to the image data. The returned buffer should not be modified and the pointer should not be cached outside the lifetime of the Image object. The data is formatted as an array of pixel color values, row by row.

You can find the exact format of each pixel by calling Image::GetNumChannels and Image::GetChannelSize. In the normal case, each pixel is represented by 4 bytes.

LONG GetPixelArraySize ( ) const

Returns the total size, in bytes, of the array returned by Image::GetPixelArray. It is expected that this is equal to the product of Image::GetResX, Image::GetResY, Image::GetNumChannels and Image::GetChannelSize.

The documentation for this class was generated from the following file:

xsi_image.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation