Coin: SbImage Class Reference

| Coin3D is Free Software, published under the BSD 3-clause license. | https://coin3d.github.io https://www.kongsberg.com/en/kogt/

Public Member Functions | Static Public Member Functions | List of all members
SbImage Class Reference
Base Classes

The SbImage class is an abstract data type for 2D and 3D images. More...

`#include <Inventor/SbImage.h>`

## Public Member Functions
| SbImage (void)
| SbImage (const unsigned char *bytes, const SbVec2s &size, const int bytesperpixel)
| SbImage (const unsigned char *bytes, const SbVec3s &size, const int bytesperpixel)
| SbImage (const SbImage &image)
| ~SbImage ()
void | setValue (const SbVec2s &size, const int bytesperpixel, const unsigned char *bytes)
void | setValue (const SbVec3s &size, const int bytesperpixel, const unsigned char *bytes)
void | setValuePtr (const SbVec2s &size, const int bytesperpixel, const unsigned char *bytes)
void | setValuePtr (const SbVec3s &size, const int bytesperpixel, const unsigned char *bytes)
unsigned char * | getValue (SbVec2s &size, int &bytesperpixel) const
unsigned char * | getValue (SbVec3s &size, int &bytesperpixel) const
SbVec3s | getSize (void) const
SbBool | readFile (const SbString &filename, const SbString *const *searchdirectories=NULL, const int numdirectories=0)
int | operator== (const SbImage &image) const
int | operator!= (const SbImage &image) const
SbImage & | operator= (const SbImage &image)
SbBool | hasData (void) const
void | readLock (void) const
void | readUnlock (void) const
SbBool | scheduleReadFile (SbImageScheduleReadCB *cb, void *closure, const SbString &filename, const SbString *const *searchdirectories=NULL, const int numdirectories=0)

## Static Public Member Functions
static void | addReadImageCB (SbImageReadImageCB *cb, void *closure)
static void | removeReadImageCB (SbImageReadImageCB *cb, void *closure)
static SbString | searchForFile (const SbString &basename, const SbString *const *dirlist, const int numdirs)

## Detailed Description

The SbImage class is an abstract data type for 2D and 3D images.

Be aware that this class is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since
  Coin 1.0

## Constructor & Destructor Documentation

## ◆ SbImage() [1/4]

SbImage::SbImage | ( | void |  | ) |

Default constructor.

## ◆ SbImage() [2/4]

SbImage::SbImage | ( | const unsigned char * | bytes,
|  | const SbVec2s & | size,
|  | const int | bytesperpixel )

Constructor which sets 2D data using setValue().

See also
  setValue()

## ◆ SbImage() [3/4]

SbImage::SbImage | ( | const unsigned char * | bytes,
|  | const SbVec3s & | size,
|  | const int | bytesperpixel )

Constructor which sets 3D data using setValue().

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

See also
  setValue()

Since
  Coin 2.0

## ◆ SbImage() [4/4]

SbImage::SbImage | ( | const SbImage & | that | ) |

Copy constructor

Since
  Coin 4.0

## ◆ ~SbImage()

SbImage::~SbImage | ( | void |  | ) |

Destructor.

## Member Function Documentation

## ◆ setValue() [1/2]

void SbImage::setValue | ( | const SbVec2s & | size,
|  | const int | bytesperpixel,
|  | const unsigned char * | bytes )

Convenience 2D version of setValue.

## ◆ setValue() [2/2]

void SbImage::setValue | ( | const SbVec3s & | size,
|  | const int | bytesperpixel,
|  | const unsigned char * | bytes )

Sets the image to size and bytesperpixel. If bytes != NULL, data is copied from bytes into this class' image data. If bytes == NULL, the image data is left uninitialized.

The image data will always be allocated in multiples of four. This means that if you set an image with size == (1,1,1) and bytesperpixel == 1, four bytes will be allocated to hold the data. This is mainly done to simplify the export code in SoSFImage and normally you'll not have to worry about this feature.

If the depth of the image (size[2]) is zero, the image is considered a 2D image.

Since
  Coin 2.0

## ◆ setValuePtr() [1/2]

void SbImage::setValuePtr | ( | const SbVec2s & | size,
|  | const int | bytesperpixel,
|  | const unsigned char * | bytes )

Convenience 2D version of setValuePtr.

See also
  setValue()

Since
  Coin 2.0

## ◆ setValuePtr() [2/2]

void SbImage::setValuePtr | ( | const SbVec3s & | size,
|  | const int | bytesperpixel,
|  | const unsigned char * | bytes )

Sets the image data without copying the data. bytes will be used directly, and the data will not be freed when the image instance is destructed.

If the depth of the image (size[2]) is zero, the image is considered a 2D image.

See also
  setValue()

Since
  Coin 2.0

## ◆ getValue() [1/2]

unsigned char * SbImage::getValue | ( | SbVec2s & | size,
|  | int & | bytesperpixel ) const

Returns the 2D image data.

## ◆ getValue() [2/2]

unsigned char * SbImage::getValue | ( | SbVec3s & | size,
|  | int & | bytesperpixel ) const

Returns the 3D image data.

Since
  Coin 2.0

## ◆ getSize()

SbVec3s SbImage::getSize | ( | void |  | ) | const

Returns the size of the image. If this is a 2D image, the z component is zero. If this is a 3D image, the z component is >= 1.

Since
  Coin 2.0

## ◆ readFile()

SbBool SbImage::readFile | ( | const SbString & | filename,
|  | const SbString *const * | searchdirectories = NULL,
|  | const int | numdirectories = 0 )

Reads image data from filename. In Coin, simage is used to load image files, and several common file formats are supported. simage can be downloaded from our web pages. If loading fails for some reason this method returns FALSE, and the instance is set to an empty image. If the file is successfully loaded, the file image data is copied into this class.

If numdirectories > 0, this method will search for filename in all directories in searchdirectories.

## ◆ operator==()

int SbImage::operator== | ( | const SbImage & | image | ) | const

Compare image of image with the image in this class and return `TRUE` if they are equal.

## ◆ operator!=()

int SbImage::operator!= | ( | const SbImage & | image | ) | const
| inline

Compare image of image with the image in this class and return `FALSE` if they are equal.

## ◆ operator=()

SbImage & SbImage::operator= | ( | const SbImage & | image | ) |

Assignment operator.

## ◆ addReadImageCB()

void SbImage::addReadImageCB | ( | SbImageReadImageCB * | cb,
|  | void * | closure )
| static

Add a callback which will be called whenever Coin wants to read an image file. The callback should return TRUE if it was able to successfully read and set the image data, and FALSE otherwise.

The callback(s) will be called before attempting to use simage to load images.

See also
  removeReadImageCB()

Since
  Coin 3.0

## ◆ removeReadImageCB()

void SbImage::removeReadImageCB | ( | SbImageReadImageCB * | cb,
|  | void * | closure )
| static

Remove a read image callback added with addReadImageCB().

See also
  addReadImageCB()

Since
  Coin 3.0

## ◆ searchForFile()

SbString SbImage::searchForFile | ( | const SbString & | basename,
|  | const SbString *const * | dirlist,
|  | const int | numdirs )
| static

Given a basename for a file and and array of directories to search (in dirlist, of length numdirs), returns the full name of the file found.

In addition to looking at the root of each directory in dirlist, we also look into the subdirectories texture/, textures/, images/, pics/ and pictures/ of each dirlist directory.

If no file matching basename could be found, returns an empty string.

## ◆ hasData()

SbBool SbImage::hasData | ( | void |  | ) | const

Returns TRUE if the image is not empty. This can be useful, since getValue() will start loading the image if scheduleReadFile() has been used to set the image data.

Since
  Coin 2.0

## ◆ readLock()

void SbImage::readLock | ( | void |  | ) | const

Apply a read lock on this image. This will make it impossible for other threads to change the image while this lock is active. Other threads can do read-only operations on this image, of course.

For the single thread version of Coin, this method does nothing.

See also
  readUnlock()

Since
  Coin 2.0

## ◆ readUnlock()

void SbImage::readUnlock | ( | void |  | ) | const

Release a read lock on this image.

For the single thread version of Coin, this method does nothing.

See also
  readLock()

Since
  Coin 2.0

## ◆ scheduleReadFile()

SbBool SbImage::scheduleReadFile | ( | SbImageScheduleReadCB * | cb,
|  | void * | closure,
|  | const SbString & | filename,
|  | const SbString *const * | searchdirectories = NULL,
|  | const int | numdirectories = 0 )

Schedule a file for reading. cb will be called the first time getValue() is called for this image, and the callback should then start a thread to read the image. Do not read the image in the callback, as this will lock up the application.

See also
  readFile()

Since
  Coin 2.0

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

- SbImage.h
- SbImage.cpp