SoRasterImageRW

java.lang.Object
- com.openinventor.inventor.Inventor
- - com.openinventor.inventor.image.SoRasterImageRW

Direct Known Subclasses:

SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoHDRImageRW, SoJP2ImageRW, SoJPEGImageRW, SoPGXImageRW, SoPNGImageRW, SoPNMImageRW, SoPSImageRW, SoSGIRGBImageRW, SoSUNImageRW, SoTIFFImageRW
```
public abstract class SoRasterImageRW
extends Inventor
```
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
- PGX
- PNG
- PNM
- SGI RGBA
- Sun
- 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 SoOffscreenRenderer 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
Load an image from a PNG format file (error checking is omitted for clarity):
```
 SoRasterImageFile inputFile = new SoRasterImageFile( "test.png" );
 
 SoPNGImageRW imageReader = new SoPNGImageRW();
 boolean ok = 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.getSizei32();
 imageWriter.writeHeader( size );
 imageWriter.write( image );
 imageWriter.writeFooter();
 imageWriter.close();
```
See also:
SoBMPImageRW, SoDDSImageRW, SoGIFImageRW, SoJP2ImageRW, SoJPEGImageRW, SoPGXImageRW, SoPNGImageRW, SoPNMImageRW, SoPSImageRW, SoSGIRGBImageRW, SoSUNImageRW, SoTIFFImageRW, SoRasterReaderSet

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SoRasterImageRW.OpenModes` open Mode enumeration values.
`static class`	`SoRasterImageRW.ReadCapabilities` Read Capability enumeration values.
`static class`	`SoRasterImageRW.WriteCapabilities` Write Capability enumeration values.

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`OPEN_READ` Deprecated. Use `SoRasterImageRW.OpenModes.OPEN_READ` instead.
`static int`	`OPEN_WRITE` Deprecated. Use `SoRasterImageRW.OpenModes.OPEN_WRITE` instead.
`static int`	`READ_AVAILABLE` Deprecated. Use `SoRasterImageRW.ReadCapabilities.READ_AVAILABLE` instead.
`static int`	`READ_UNAVAILABLE` Deprecated. Use `SoRasterImageRW.ReadCapabilities.READ_UNAVAILABLE` instead.
`static int`	`WRITE_FULL_IMAGE` Deprecated. Use `SoRasterImageRW.WriteCapabilities.WRITE_FULL_IMAGE` instead.
`static int`	`WRITE_SCANLINES` Deprecated. Use `SoRasterImageRW.WriteCapabilities.WRITE_SCANLINES` instead.
`static int`	`WRITE_UNAVAILABLE` Deprecated. Use `SoRasterImageRW.WriteCapabilities.WRITE_UNAVAILABLE` instead.

Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`checkRead(SoRasterImageFile imageFile)` Checks if the specified file can be read.
`void`	`close()` Closes the reader/writer.
`void`	`enableMultipleWriting(boolean state)` Enable writing image with multiple calls to write method.
`SoRasterImageRW.ReadCapabilities`	`getReadCapability()` Returns the read capability of the raster format.
`SoRasterImageRW.WriteCapabilities`	`getWriteCapability()` Returns the write capability of the raster format.
`boolean`	`isMultipleBufferInverted()` Returns the write order when using multiple buffers.
`boolean`	`isMultipleWritingEnabled()` Returns true if multiple buffer writing is enabled.
`boolean`	`open(SoRasterImageIO rasterImageIO, SoRasterImageRW.OpenModes openMode)` Opens the reader/writer in the specified open mode.
`boolean`	`read(SbRasterImage rasterImage)` Calls read(rasterImage, false).
`boolean`	`read(SbRasterImage rasterImage, boolean infoOnly)` Read the current open image into rasterImage.
`boolean`	`readRegion(SbRasterImage rasterImage, SbBox2i32 region)` Read the specified region of current open image into rasterImage.
`boolean`	`write(SbRasterImage rasterImage)` Calls write(rasterImage, (int)0, (int)0).
`boolean`	`write(SbRasterImage rasterImage, int xPos)` Calls write(rasterImage, xPos, (int)0).
`boolean`	`write(SbRasterImage rasterImage, int xPos, int yPos)` Writes and encodes the given data in the specific format.
`boolean`	`writeFooter()` Writes and encodes the footer for this specific format.
`boolean`	`writeHeader(SbVec2i32 size)` Writes and encodes the header for this specific format.
`boolean`	`writeHeader(SbVec2s size)` Deprecated. As of Open Inventor 8.0, use `writeHeader(SbVec2i32 size)` instead.

Methods inherited from class com.openinventor.inventor.Inventor
dispose, getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WRITE_SCANLINES
```
@Deprecated
public static final int WRITE_SCANLINES
```
    Deprecated. Use SoRasterImageRW.WriteCapabilities.WRITE_SCANLINES instead.
  - WRITE_FULL_IMAGE
```
@Deprecated
public static final int WRITE_FULL_IMAGE
```
    Deprecated. Use SoRasterImageRW.WriteCapabilities.WRITE_FULL_IMAGE instead.
  - WRITE_UNAVAILABLE
```
@Deprecated
public static final int WRITE_UNAVAILABLE
```
    Deprecated. Use SoRasterImageRW.WriteCapabilities.WRITE_UNAVAILABLE instead.
  - READ_AVAILABLE
```
@Deprecated
public static final int READ_AVAILABLE
```
    Deprecated. Use SoRasterImageRW.ReadCapabilities.READ_AVAILABLE instead.
  - READ_UNAVAILABLE
```
@Deprecated
public static final int READ_UNAVAILABLE
```
    Deprecated. Use SoRasterImageRW.ReadCapabilities.READ_UNAVAILABLE instead.
  - OPEN_READ
```
@Deprecated
public static final int OPEN_READ
```
    Deprecated. Use SoRasterImageRW.OpenModes.OPEN_READ instead.
  - OPEN_WRITE
```
@Deprecated
public static final int OPEN_WRITE
```
    Deprecated. Use SoRasterImageRW.OpenModes.OPEN_WRITE instead.
- Method Detail
  - writeHeader
```
@Deprecated
public boolean writeHeader(SbVec2s size)
```
    Deprecated. As of Open Inventor 8.0, use writeHeader(SbVec2i32 size) instead.
    
    Writes and encodes the header for this specific format. The parameter is the size of the whole raster image to be saved. The size is limited to 32767 by 32767
  - read
```
public boolean read(SbRasterImage rasterImage)
```
    Calls read(rasterImage, false).
  - write
```
public boolean write(SbRasterImage rasterImage,
                     int xPos)
```
    Calls write(rasterImage, xPos, (int)0).
  - write
```
public boolean write(SbRasterImage rasterImage)
```
    Calls write(rasterImage, (int)0, (int)0).
  - getReadCapability
```
public SoRasterImageRW.ReadCapabilities getReadCapability()
```
    Returns the read capability of the raster format. Returns READ_AVAILABLE by default.
  - read
```
public boolean read(SbRasterImage rasterImage,
                    boolean infoOnly)
```
    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.
  - getWriteCapability
```
public SoRasterImageRW.WriteCapabilities getWriteCapability()
```
    Returns the write capability of the raster format. Returns WRITE_SCANLINES by default.
  - writeFooter
```
public boolean writeFooter()
```
    Writes and encodes the footer for this specific format. Returns true if successful.
  - readRegion
```
public boolean readRegion(SbRasterImage rasterImage,
                          SbBox2i32 region)
```
    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.
  - isMultipleBufferInverted
```
public boolean isMultipleBufferInverted()
```
    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.
  - writeHeader
```
public boolean writeHeader(SbVec2i32 size)
```
    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.
  - checkRead
```
public boolean checkRead(SoRasterImageFile imageFile)
```
    Checks if the specified file can be read. Returns true if successful.
  - close
```
public void close()
```
    Closes the reader/writer.
  - open
```
public boolean open(SoRasterImageIO rasterImageIO,
                    SoRasterImageRW.OpenModes openMode)
```
    Opens the reader/writer in the specified open mode. Returns true if successful.
  - enableMultipleWriting
```
public void enableMultipleWriting(boolean state)
```
    Enable writing image with multiple calls to write method. Default is false.
  - write
```
public boolean write(SbRasterImage rasterImage,
                     int xPos,
                     int yPos)
```
    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.
  - isMultipleWritingEnabled
```
public boolean isMultipleWritingEnabled()
```
    Returns true if multiple buffer writing is enabled.

Class SoRasterImageRW

Nested Class Summary

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Field Summary

Fields inherited from class com.openinventor.inventor.Inventor

Method Summary

Methods inherited from class com.openinventor.inventor.Inventor

Methods inherited from class java.lang.Object

Field Detail

WRITE_SCANLINES

WRITE_FULL_IMAGE

WRITE_UNAVAILABLE

READ_AVAILABLE

READ_UNAVAILABLE

OPEN_READ

OPEN_WRITE

Method Detail

writeHeader

read

write

write

getReadCapability

read

getWriteCapability

writeFooter

readRegion

isMultipleBufferInverted

writeHeader

checkRead

close

open

enableMultipleWriting

write

isMultipleWritingEnabled