Abstract base class for encoding and decoding raster images. More...

#include <Inventor/image/SoRasterImageRW.h>

Inheritance diagram for SoRasterImageRW:

Public Types
enum	WriteCapability { WRITE_SCANLINES , WRITE_FULL_IMAGE , WRITE_UNAVAILABLE }
	Write Capability enumeration values. More...

enum	ReadCapability { READ_AVAILABLE , READ_UNAVAILABLE }
	Read Capability enumeration values. More...

enum	OpenMode { OPEN_READ , OPEN_WRITE }
	open Mode enumeration values. More...

Public Member Functions
virtual SoType	getTypeId () const =0
	Returns the type identifier for this specific instance.

virtual	~SoRasterImageRW ()
	Destructor.

virtual SbBool	open (SoRasterImageIO *rasterImageIO, OpenMode openMode)
	Opens the reader/writer in the specified open mode.

virtual void	close ()
	Closes the reader/writer.

virtual SbBool	checkRead (SoRasterImageFile *imageFile)
	Checks if the specified file can be read.

virtual SbBool	write (SbRasterImage *rasterImage, unsigned int xPos=0, unsigned int yPos=0)=0
	Writes and encodes the given data in the specific format.

virtual SbBool	writeHeader (const SbVec2i32 &size)
	Writes and encodes the header for this specific format.

virtual SbBool	writeFooter ()
	Writes and encodes the footer for this specific format.

virtual SbBool	read (SbRasterImage *rasterImage, SbBool infoOnly=FALSE)=0
	Read the current open image into rasterImage.

virtual SbBool	readRegion (SbRasterImage *rasterImage, const SbBox2i32 &region)
	Read the specified region of current open image into rasterImage.

virtual SbString *	getSuffixes (int &numSuffixes) const
	Returns the list of file suffixes supported.

virtual SbBool	isMultipleBufferInverted () const
	Returns the write order when using multiple buffers.

virtual SoRasterImageRW::WriteCapability	getWriteCapability () const
	Returns the write capability of the raster format.

virtual SoRasterImageRW::ReadCapability	getReadCapability () const
	Returns the read capability of the raster format.

virtual void	enableMultipleWriting (SbBool state)
	Enable writing image with multiple calls to write method.

virtual SbBool	isMultipleWritingEnabled () const
	Returns TRUE if multiple buffer writing is enabled.

Deprecated

virtual SoDEPRECATED SbBool	writeHeader (SbVec2i32 &size)
	Writes and encodes the header for this specific format.

virtual SoDEPRECATED SbBool	writeHeader (SbVec2s &size)
	Writes and encodes the header for this specific format.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Detailed Description

Abstract base class for encoding and decoding raster images.

SoRasterImageRW is the base class used for encoding and decoding raster images.

The following file formats are supported for raster image input (i.e., read):

BMP (Windows only)
DDS
GIF
HDRI (with SoTextureCubeMap only)
JPEG 2000
JPEG
PNG
SGI RGBA
TIFF

The following formats are supported for raster image output (i.e., write):

All the above except GIF (read only), plus
PS (PostScript), which is available for writing only.

Note that only the following image file formats can contain transparency (alpha channel) information:

DDS
GIF
PNG
SGI RGBA
TIFF

There is a subclass of SoRasterImageRW for each of the above formats.

The convenience class SoRasterReaderSet can be used to determine the appropriate reader class for an image file by attempting to read the file using each of the built-in reader classes.

A subclass of SoRasterImageIO, e.g. SoRasterImageFile, must be used as the source of a read operation or the destination of a write operation.

Note that it is not necessary to explicitly load image files for common operations like texture mapping. SoTexture2, for example, automatically loads the image file specified in its filename field.

SoRasterImageRW classes support two methods of writing out an image. The simplest one is writing out a complete image already assembled in memory. This is the default method and is efficiently supported by all image formats. SoRasterImageRW also supports assembling an image from multiple sub-images or "tiles". The SoOffscreenRenderArea class, for example, uses this feature when the requested image size is too large for OpenGL to render as a single image. To use this feature call the enableMultipleWriting method with TRUE. Note that some image formats allow the image to be written (encoded) incrementally, so tiles provided in scan-line order can written immediately, with no intermediate storage. Other image formats cannot be encoded until the complete image is assembled in memory.

Image formats that allow tiles to be written incrementally have the writeCapability WRITE_SCANLINES. This is the most memory efficient way to write large images. Note that some image formats are encoded from top to bottom and some are encoded from bottom to top. The method isMultipleBufferInverted returns TRUE if the format should be encoded from bottom to top.

Image formats that require a complete image before encoding have the writeCapability WRITE_FULL_IMAGE. In this case the SoRasterImageRW subclass will automatically allocate enough memory to hold the complete image. This may require a very large block of contiguous memory! The image is not actually written until the writeFooter method is called.

EXAMPLE

SoRasterImageFile inputFile( "test.png" );
 
SoPNGImageRW imageReader;
imageReader.open( &inputFile, SoRasterImageRW::OPEN_READ );
 
SbRasterImage image;
imageReader.read( &image );
imageReader.close();

EXAMPLE

SoRasterImageFile outputFile( "test.jpg" );
 
SoJPEGImageRW imageWriter;
imageWriter.open( &outputFile, SoRasterImageRW::OPEN_WRITE );
 
SbRasterImage image . . .; // Previously created
SbVec2i32 size = image.getSize_i32();
imageWriter.writeHeader( size );
imageWriter.write( &image );
imageWriter.writeFooter();
imageWriter.close();

Member Enumeration Documentation

◆ OpenMode

enum SoRasterImageRW::OpenMode

open Mode enumeration values.

Enumerator
OPEN_READ	Opened for reading.
OPEN_WRITE	Opened for writing.

Definition at line 251 of file SoRasterImageRW.h.

◆ ReadCapability

enum SoRasterImageRW::ReadCapability

Read Capability enumeration values.

Enumerator
READ_AVAILABLE	Read functionality available.
READ_UNAVAILABLE	No reading available.

Definition at line 239 of file SoRasterImageRW.h.

◆ WriteCapability

enum SoRasterImageRW::WriteCapability

Write Capability enumeration values.

Enumerator
WRITE_SCANLINES	Can write an image incrementally (e.g., by scan-line).
WRITE_FULL_IMAGE	Can only write a complete image.
WRITE_UNAVAILABLE	No writing available.

Definition at line 223 of file SoRasterImageRW.h.

Constructor & Destructor Documentation

◆ ~SoRasterImageRW()

virtual SoRasterImageRW::~SoRasterImageRW ( )

virtual

Destructor.

Member Function Documentation

◆ checkRead()

virtual SbBool SoRasterImageRW::checkRead ( SoRasterImageFile * imageFile )

virtual

Checks if the specified file can be read.

Returns true if successful.

◆ close()

virtual void SoRasterImageRW::close ( )

virtual

Closes the reader/writer.

Reimplemented in SoBMPImageRW, and SoJPEGImageRW.

◆ enableMultipleWriting()

virtual void SoRasterImageRW::enableMultipleWriting ( SbBool state )

virtual

Enable writing image with multiple calls to write method.

Default is FALSE.

◆ getClassTypeId()

static SoType SoRasterImageRW::getClassTypeId ( )

static

Returns the type identifier for this class.

◆ getReadCapability()

virtual SoRasterImageRW::ReadCapability SoRasterImageRW::getReadCapability ( ) const

virtual

Returns the read capability of the raster format.

Returns READ_AVAILABLE by default.

Reimplemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoPNGImageRW, SoPSImageRW, and SoSGIRGBImageRW.

◆ getSuffixes()

virtual SbString * SoRasterImageRW::getSuffixes ( int & numSuffixes ) const

virtual

Returns the list of file suffixes supported.

Return value is a pointer to an array containing numSuffixes SbString objects. This is internal object memory. Do NOT delete or modify.

◆ getTypeId()

virtual SoType SoRasterImageRW::getTypeId ( ) const

pure virtual

Returns the type identifier for this specific instance.

Implemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoMRCImageRW, SoPNGImageRW, SoPSImageRW, SoSGIRGBImageRW, and SoTIFFImageRW.

◆ getWriteCapability()

virtual SoRasterImageRW::WriteCapability SoRasterImageRW::getWriteCapability ( ) const

virtual

Returns the write capability of the raster format.

Returns WRITE_SCANLINES by default.

Reimplemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoPNGImageRW, SoPSImageRW, and SoSGIRGBImageRW.

◆ isMultipleBufferInverted()

virtual SbBool SoRasterImageRW::isMultipleBufferInverted ( ) const

virtual

Returns the write order when using multiple buffers.

Returns FALSE if buffers are written from top to bottom. Returns TRUE if buffers are written from bottom to top. Returns TRUE by default.

Reimplemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoPNGImageRW, SoPSImageRW, and SoSGIRGBImageRW.

◆ isMultipleWritingEnabled()

virtual SbBool SoRasterImageRW::isMultipleWritingEnabled ( ) const

virtual

Returns TRUE if multiple buffer writing is enabled.

◆ open()

virtual SbBool SoRasterImageRW::open	(	SoRasterImageIO *	rasterImageIO,
		OpenMode	openMode
	)

virtual

Opens the reader/writer in the specified open mode.

Returns true if successful.

Reimplemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoMRCImageRW, SoPNGImageRW, SoSGIRGBImageRW, and SoTIFFImageRW.

◆ read()

virtual SbBool SoRasterImageRW::read	(	SbRasterImage *	rasterImage,
		SbBool	infoOnly = `FALSE`
	)

pure virtual

Read the current open image into rasterImage.

Returns true if successful. Call the open() method before calling this method.

If infoOnly is TRUE, then the buffer will not be read; the parameter rasterImage will be set with raster size and raster number of components, the buffer will be NULL.

Implemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoMRCImageRW, SoPNGImageRW, SoPSImageRW, SoSGIRGBImageRW, and SoTIFFImageRW.

◆ readRegion()

virtual SbBool SoRasterImageRW::readRegion	(	SbRasterImage *	rasterImage,
		const SbBox2i32 &	region
	)

virtual

Read the specified region of current open image into rasterImage.

Returns true if successful. Call the open() method before calling this method.

After calling this method successfully, the size of the SbRasterImage is the requested region size. The requested region may extend outside the source image. In this case, undefined pixels are set to zero. The region may be as small as a single pixel, e.g. (1,1,1,1), but xmin must be <= xmax and ymin <= ymax.

Reimplemented in SoJP2ImageRW, SoMRCImageRW, and SoTIFFImageRW.

◆ write()

virtual SbBool SoRasterImageRW::write	(	SbRasterImage *	rasterImage,
		unsigned int	xPos = `0`,
		unsigned int	yPos = `0`
	)

pure virtual

Writes and encodes the given data in the specific format.

Returns true if successful. If you are using the multiple writing mode, then you can give the offset with (xPos,yPos) you want to write to.

Implemented in SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoMRCImageRW, SoPNGImageRW, SoPSImageRW, SoSGIRGBImageRW, and SoTIFFImageRW.

◆ writeFooter()

virtual SbBool SoRasterImageRW::writeFooter ( )

virtual

Writes and encodes the footer for this specific format.

Returns true if successful.

Reimplemented in SoBMPImageRW, SoHDRImageRW, SoJPEGImageRW, SoPSImageRW, and SoSGIRGBImageRW.

◆ writeHeader() [1/3]

virtual SbBool SoRasterImageRW::writeHeader ( const SbVec2i32 & size )

virtual

Writes and encodes the header for this specific format.

Returns true if successful. The parameter is the size of the whole raster image to be saved. Use for sizes with at least one side greater than 32767.

◆ writeHeader() [2/3]

virtual SoDEPRECATED SbBool SoRasterImageRW::writeHeader ( SbVec2i32 & size )

virtual

Writes and encodes the header for this specific format.

Returns true if successful. The parameter is the size of the whole raster image to be saved. Use for sizes with at least one side greater than 32767.

◆ writeHeader() [3/3]

virtual SoDEPRECATED SbBool SoRasterImageRW::writeHeader ( SbVec2s & size )

virtual

Writes and encodes the header for this specific format.

Returns true if successful. The parameter is the size of the whole raster image to be saved. The size is limited to 32767 by 32767

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

Inventor/image/SoRasterImageRW.h

Open Inventor Release 2024.2.0

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

EXAMPLE

EXAMPLE

SEE ALSO

Member Enumeration Documentation

◆ OpenMode

◆ ReadCapability

◆ WriteCapability

Constructor & Destructor Documentation

◆ ~SoRasterImageRW()

Member Function Documentation

◆ checkRead()

◆ close()

◆ enableMultipleWriting()

◆ getClassTypeId()

◆ getReadCapability()

◆ getSuffixes()

◆ getTypeId()

◆ getWriteCapability()

◆ isMultipleBufferInverted()

◆ isMultipleWritingEnabled()

◆ open()

◆ read()

◆ readRegion()

◆ write()

◆ writeFooter()

◆ writeHeader() [1/3]

◆ writeHeader() [2/3]

◆ writeHeader() [3/3]