Class SoRasterImageRW
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.image.SoRasterImageRW
-
- Direct Known Subclasses:
SoBMPImageRW
,SoDDSImageRW
,SoGIFImageRW
,SoHDRImageRW
,SoJP2ImageRW
,SoJPEGImageRW
,SoMRCImageRW
,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". TheSoOffscreenRenderArea
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();
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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 inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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.-
Methods inherited from class com.openinventor.inventor.Inventor
dispose, getNativeResourceHandle
-
-
-
-
Method Detail
-
read
public boolean read(SbRasterImage rasterImage)
Calls read(rasterImage, false).
-
write
public boolean write(SbRasterImage rasterImage)
Calls write(rasterImage, (int)0, (int)0).
-
write
public boolean write(SbRasterImage rasterImage, int xPos)
Calls write(rasterImage, xPos, (int)0).
-
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.
-
open
public boolean open(SoRasterImageIO rasterImageIO, SoRasterImageRW.OpenModes openMode)
Opens the reader/writer in the specified open mode. Returns true if successful.
-
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 theopen()
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.
-
read
public boolean read(SbRasterImage rasterImage, boolean infoOnly)
Read the current open image into rasterImage. Returns true if successful. Call theopen()
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.
-
checkRead
public boolean checkRead(SoRasterImageFile imageFile)
Checks if the specified file can be read. Returns true if successful.
-
isMultipleWritingEnabled
public boolean isMultipleWritingEnabled()
Returns true if multiple buffer writing is enabled.
-
close
public void close()
Closes the reader/writer.
-
enableMultipleWriting
public void enableMultipleWriting(boolean state)
Enable writing image with multiple calls to write method. Default is false.
-
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.
-
getReadCapability
public SoRasterImageRW.ReadCapabilities getReadCapability()
Returns the read capability of the raster format. Returns READ_AVAILABLE by default.
-
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.
-
-