Click or drag to resize
SoRasterImageRW Class

Abstract base class for encoding and decoding raster images.

Inheritance Hierarchy
SystemObject
  OIV.InventorSoNetBase
    OIV.Inventor.ImageSoRasterImageRW
      More...

Namespace: OIV.Inventor.Image
Assembly: OIV.Inventor (in OIV.Inventor.dll) Version: 2023.2.2.0 (2023.2.2)
Syntax
public class SoRasterImageRW : SoNetBase

The SoRasterImageRW type exposes the following members.

Methods
  NameDescription
Public methodCheckRead

Checks if the specified file can be read.

Public methodClose

Closes the reader/writer.

Public methodEnableMultipleWriting

Enable writing image with multiple calls to write method.

Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodGetHashCode
Overrides GetHashCode().
(Inherited from SoNetBase.)
Public methodGetReadCapability

Returns the read capability of the raster format.

Public methodGetSuffixes

Returns the list of file suffixes supported.

Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodGetWriteCapability

Returns the write capability of the raster format.

Public methodIsMultipleBufferInverted

Returns the write order when using multiple buffers.

Public methodIsMultipleWritingEnabled

Returns true if multiple buffer writing is enabled.

Public methodOpen

Opens the reader/writer in the specified open mode.

Public methodRead(SbRasterImage)
Calls Read(rasterImage, false).
Public methodRead(SbRasterImage, Boolean)

Read the current open image into rasterImage.

Public methodReadRegion

Read the specified region of current open image into rasterImage.

Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodWrite(SbRasterImage)
Calls Write(rasterImage, System.UInt32(0), System.UInt32(0)).
Public methodWrite(SbRasterImage, UInt32)
Calls Write(rasterImage, xPos, System.UInt32(0)).
Public methodWrite(SbRasterImage, UInt32, UInt32)

Writes and encodes the given data in the specific format.

Public methodWriteFooter
Public methodWriteHeader(SbVec2i32)

Writes and encodes the header for this specific format.

Public methodWriteHeader(SbVec2s) Obsolete.

Writes and encodes the header for this specific format.

Top
Remarks

OIV.Inventor.Image.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):

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 OIV.Inventor.Image.SoRasterImageRW for each of the above formats.

The convenience class OIV.Inventor.Image.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 OIV.Inventor.Image.SoRasterImageIO, e.g. OIV.Inventor.Image.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. OIV.Inventor.Nodes.SoTexture2, for example, automatically loads the image file specified in its filename field.

OIV.Inventor.Image.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. OIV.Inventor.Image.SoRasterImageRW also supports assembling an image from multiple sub-images or "tiles". The OIV.Inventor.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 OIV.Inventor.Image.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

Load an image from a PNG format file (error checking is omitted for clarity):

SoRasterImageFile inputFile = new SoRasterImageFile( "test.png" );

SoPNGImageRW imageReader = new SoPNGImageRW();
imageReader.Open( inputFile, SoRasterImageRW.OpenModes.OPEN_READ );

SbRasterImage image = new SbRasterImage();
imageReader.Read(image);
imageReader.Close();

EXAMPLE

Write an image to a JPEG format file (error checking is omitted for clarity):

SoRasterImageFile outputFile = new SoRasterImageFile("test.jpg");

SoJPEGImageRW imageWriter = new SoJPEGImageRW();
imageWriter.Open(outputFile, SoRasterImageRW.OpenModes.OPEN_WRITE);

SbRasterImage image . . .; // Previously created
SbVec2i32 size = image.GetSize_i32();
imageWriter.WriteHeader( size );
imageWriter.Write( image );
imageWriter.WriteFooter();
imageWriter.Close();

See Also
Inheritance Hierarchy
SystemObject
  OIV.InventorSoNetBase
    OIV.Inventor.ImageSoRasterImageRW
      OIV.Inventor.ImageSoBMPImageRW
      OIV.Inventor.ImageSoDDSImageRW
      OIV.Inventor.ImageSoGIFImageRW
      OIV.Inventor.ImageSoHDRImageRW
      OIV.Inventor.ImageSoJP2ImageRW
      OIV.Inventor.ImageSoJPEGImageRW
      OIV.Inventor.ImageSoMRCImageRW
      OIV.Inventor.ImageSoPGXImageRW
      OIV.Inventor.ImageSoPNGImageRW
      OIV.Inventor.ImageSoPNMImageRW
      OIV.Inventor.ImageSoPSImageRW
      OIV.Inventor.ImageSoSGIRGBImageRW
      OIV.Inventor.ImageSoSUNImageRW
      OIV.Inventor.ImageSoTIFFImageRW