SoVolumeData(3)

📦 version 2.1.0, in fedora 43, fedora 44

🎀 NAME 🎀

Welcome to SoVolumeData(3), bestie 💖 SoVolumeData — the main interface for setting up volume data sets.

📜 SYNOPSIS 📜

#include <VolumeViz/nodes/SoVolumeData.h>

Inherits SoVolumeRendering.

🌈 Public Types

enum StorageHint { AUTO, TEX2D_MULTI, TEX2D = TEX2D_MULTI, TEX3D, MEMORY, VOLUMEPRO, TEX2D_SINGLE }
enum SubMethod { NEAREST, MAX, AVERAGE }
enum OverMethod { NONE, CONSTANT, LINEAR, CUBIC }
enum DataType { UNSIGNED_BYTE, UNSIGNED_SHORT }

💫 Public Types inherited from SoVolumeRendering

enum HW_Feature { HW_VOLUMEPRO, HW_3DTEXMAP, HW_TEXCOLORMAP, HW_TEXCOMPRESSION }
enum HW_SupportStatus { NO, YES, UNKNOWN }

🫶 Public Member Functions

  • void setVolumeData (const SbVec3s &dimension, void *data, SoVolumeData::DataType type=SoVolumeData::UNSIGNED_BYTE, int significantbits=0)
  • SbBool getVolumeData (SbVec3s &dimension, void *&data, SoVolumeData::DataType &type, int *significantbits=NULL) const
  • uint32_t getVoxelValue (const SbVec3s &voxelpos) const
  • void setVolumeSize (const SbBox3f &size)
  • SbBox3f getVolumeSize (void) const
  • void setPageSize (int size)
  • void setPageSize (const SbVec3s &size)
  • const SbVec3s & getPageSize (void) const
  • void setReader (SoVolumeReader &reader)
  • SoVolumeReader * getReader (void) const
  • void setTexMemorySize (int megatexels)
  • int getTexMemorySize (void) const
  • SbBool getMinMax (int &minval, int &maxval)
  • SbBool getHistogram (int &length, int *&histogram)
  • SoVolumeData * subSetting (const SbBox3s &region)
  • void updateRegions (const SbBox3s *region, int num)
  • void loadRegions (const SbBox3s *region, int num, SoState *state, SoTransferFunction *node)
  • SoVolumeData * reSampling (const SbVec3s &dimension, SoVolumeData::SubMethod subMethod, SoVolumeData::OverMethod=NONE)
  • void enableSubSampling (SbBool enable)
  • SbBool isSubSamplingEnabled (void) const
  • void enableAutoSubSampling (SbBool enable)
  • SbBool isAutoSubSamplingEnabled (void) const
  • void enableAutoUnSampling (SbBool enable)
  • SbBool isAutoUnSamplingEnabled (void) const
  • void unSample (void)
  • void setSubSamplingMethod (SubMethod method)
  • SubMethod getSubSamplingMethod (void) const
  • void setSubSamplingLevel (const SbVec3s &roi, const SbVec3s &secondary)
  • void getSubSamplingLevel (SbVec3s &roi, SbVec3s &secondary) const

💅 Public Member Functions inherited from SoVolumeRendering

  • HW_SupportStatus isSupported (HW_Feature feature)

⭐ Static Public Member Functions

  • static void initClass (void)

✨ Static Public Member Functions inherited from SoVolumeRendering

  • static void init (void)
  • static void initClass (void)
  • static void setReadAlternateRep (SbBool flag)
  • static void setWriteAlternateRep (SbBool flag)
  • static SbBool getReadAlternateRep (void)
  • static SbBool getWriteAlternateRep (void)
  • static void setDelayedRendering (SbBool flag)
  • static SbBool getDelayedRendering (void)

🍓 Public Attributes

  • SoSFString fileName
  • SoSFEnum storageHint
  • SoSFBool usePalettedTexture
  • SoSFBool useSharedPalettedTexture
  • SoSFBool useCompressedTexture

🔒 Protected Member Functions

  • virtual void doAction (SoAction *action)
  • virtual void GLRender (SoGLRenderAction *action)
  • virtual void callback (SoCallbackAction *action)
  • virtual void getBoundingBox (SoGetBoundingBoxAction *action)
  • virtual void pick (SoPickAction *action)

🧚 Friends

  • class SoVolumeDataP

🌸 Detailed Description 🌸

The main interface for setting up volume data sets.

okay so this node class is literally the interface for setting up the voxel data you're about to render. Want a full, stand-alone usage example? Go peek at the SIM Voleon main page documentation — it's giving tutorial energy fr fr.

Volume data is, by default, normalized to live inside a 2x2x2 unit dimensions cube. But bestie, heads up — that's actually up to the reader classes, so it might not be the same for every reader. Check the individual class docs for whatever file formats you're using, iykyk. 👑

Like, say you set up a voxel data set with dimensions 100x400x200. That's gonna render inside a bounding box of <-0.25, -1, -0.5> to <0.25, 1, 0.5>. Notice how the largest dimension (the Y dimension here) gets made to fit within unit size 2, and the other dimensions get scaled to match? That's the vibe. 💅

You can use SoVolumeData::setVolumeSize() to force a different unit size box around the volume, or honestly you can just use the standard Coin transformation nodes — like, e.g. SoScale — to accomplish the same thing. Whatever slays for you.

The volume rendering of SIM Voleon works well on volume data sets of any dimensions. Meanwhile, with other volume rendering systems, it's often necessary to accommodate the rendering system by pre-processing the dataset to be of power-of-two dimensions — either to avoid the rendering eating up an extraordinary amount of resources related to texture-mapping, or from just down-right failing. 😭 That restriction is not present in SIM Voleon, which works well with different dimensions along the principal axes, and with any non-power-of-two dimension. Iconic behavior, honestly.

If the volume data is set from a memory location with the SoVolumeData::setVolumeData() method, the voxel data can be changed during visualization at will. But after making a batch of changes, make sure you notify the node that data has been modified by doing the following:

volumedatanode->touch();

Internal regeneration of textures etc for visualization will then be done automatically by the SIM Voleon rendering system. No cap. ✨

🔧 Member Function Documentation 🔧

void SoVolumeData::setVolumeData (const SbVec3s & dimensions, void * data, SoVolumeData::DataType type = SoVolumeData::UNSIGNED_BYTE, int significantbits = 0)

This one lets you set up a volume data set from data sitting in memory, instead of loading it from a file (which would be through the SoVolumeData::fileName field). 🫶

data should point to the block of voxels, of the data size given by type. And dimensions specifies the size layout of the voxel array along the 3 axes.

Real talk: the data block you pass in here will not be freed when the node is destructed, or when you set new data — that's considered the responsibility of the caller. You own it, bestie. 💀

The input data will be mapped to the world coordinate system like this: increasing memory addresses get mapped first to increasing voxel positions along the X axis, row by row. Then the rows get mapped to increasing positions along the Y axis, making up slices. Then the slices get mapped to increasing Z axis positions. Clean, orderly, gorgeous. 🌈

The data will be mapped to be within a cube of size 2x2x2, where the largest voxel dimension(s) will be used to normalize the other dimensions.

As an example, if you set up a voxel data set of dimensions 100x400x200, this will be rendered within a bounding box of <-0.25, -1, -0.5> to <0.25, 1, 0.5>. Notice that the largest dimension (the Y dimension in this example) will be made to fit within unit size 2, and the other dimensions will be scaled accordingly. Math ate. 🧮💖

SbBool SoVolumeData::getVolumeData (SbVec3s & dimensions, void *& data, SoVolumeData::DataType & type, int * significantbits = NULL) const

Returns info about the voxel dimensions, a data pointer to the memory block of voxels, and a type indicator for how many bytes are used for each voxel.

The return value is FALSE if the data could not be loaded. 🙈

uint32_t SoVolumeData::getVoxelValue (const SbVec3s & voxelpos) const

Returns the "raw" value of the voxel at the given position. Raw. Unfiltered. Main character energy. ✨

void SoVolumeData::setVolumeSize (const SbBox3f & size)

Sets the geometric size of the volume.

This will override the value found in a volumedata file by a reader (if any). So yeah, it wins the argument. 💅

SbBox3f SoVolumeData::getVolumeSize (void ) const

Returns the geometric size of the volume.

void SoVolumeData::setPageSize (int size)

Sets the largest internal size of texture pages and texture cubes. This sets all dimensions to the same value at once. Default value is 128^3.

The size value must be a power of two. 🚨

This is essentially of interest only for the internal implementation, and should usually not be necessary to change from application code.

References setPageSize().

Referenced by setPageSize().

void SoVolumeData::setPageSize (const SbVec3s & texsize)

Sets the largest internal size of texture pages and texture cubes. Default value is [128, 128, 128].

All elements of texsize must be a power of two. 🚨

This is essentially of interest only for the internal implementation, and should usually not be necessary to change from application code.

const SbVec3s & SoVolumeData::getPageSize (void ) const

Returns the internal dimensions of each 2D texture rectangle or 3D texture cube. 📐

void SoVolumeData::setTexMemorySize (int megatexels)

Set the maximum number of texels we can bind up for 2D and 3D textures for volume rendering. The value is given in number of megatexels — like, an argument value "16" will be interpreted to set the limit at 16*1024*1024=16777216 texels.

Note that you can in general not know in advance how much actual texture memory a texel is going to use, because textures can be paletted with a variable number of bits-pr-texel, and even compressed before being transferred to the graphics card's on-chip memory. Sneaky little texels. 👀

Due to the above mentioned reasons, the usefulness of this method is rather dubious, but it is still included for compatibility with TGS VolumeViz API extension to Open Inventor. (Legacy support behavior, we respect it. 🫡)

The default value is to allow unlimited texture memory usage. This means that it's up to the underlying OpenGL driver to take care of the policy of how to handle scarcity of resources. This is the recommended strategy from OpenGL documentation.

Note that SIM Voleon's default differs from TGS's VolumeViz default, which is set at 64 megatexels.

int SoVolumeData::getTexMemorySize (void ) const

Returns the limitation forced on texture memory usage.

See also

  • SoVolumeData::setTexMemorySize()

Since

  • SIM Voleon 2.0

SbBool SoVolumeData::getHistogram (int & length, int *& histogram)

Returns a reference to a histogram of all voxel values. length will be set to either 256 for 8-bit data or 65356 for 16-bit data.

At each index of the histogram table, there will be a value indicating the number of voxels that has the data value corresponding to the index.

Return value is always TRUE. Periodt. ✅

void SoVolumeData::loadRegions (const SbBox3s * region, int num, SoState * state, SoTransferFunction * node)

Force loading of the given subregion. This function should usually not be of interest to the application programmer. (Internal business only, bestie — nothing to see here. 🙈)

Since

  • SIM Voleon 2.0

…and that's only part 1, so don't you dare leave, there's literally more coming 💖

💖 Member Data Documentation 💖

🎀 SoSFBool SoVolumeData::usePalettedTexture

okay so this one is literally the "are we doing paletted textures or not" switch, bestie. 💅

Paletted textures uses only 1/4th of the amount of graphics card memory resources versus ordinary RGBA textures, with no degradation of rendering quality. no cap, that's a whole glow-up for your GPU memory fr fr. ✨

Not all graphics cards and drivers supports paletted textures, but the library will fall back on non-paletted textures automatically if that is the case. so like, no stress, it's got you. 🫶

SIM Voleon supports two different OpenGL techniques for doing paletted textures: either through using the GL_EXT_paletted_texture extension available on many older OpenGL drivers, or by using fragment shader programs, the latter typically available on most modern OpenGL drivers. iconic versatility honestly. 👑

Default value of this field is TRUE. Apart from debugging purposes, there are not many good reasons to set this field to FALSE. lowkey just leave it on unless you're debugging something.

It might however be of interest if one wants to take advantage of the typically larger resource savings which can be made from setting SoVolumeData::useCompressedTexture to TRUE, as that hint will be overridden by a TRUE value in this field (as long as paletted textures are actually supported by the OpenGL driver).

This because paletted textures can not be "lossy" compressed, so only one of paletted textures and texture compression can be active at the same time -- not both of them. The policy of SIM Voleon is to prefer paletted textures, as that has certain other beneficial effects apart from resource savings, mainly that one can modify the SoTransferFunction at run-time with no rendering performance hit. periodt. ✨

🦋 SoSFBool SoVolumeData::useSharedPalettedTexture

Indicate whether or not to share texture palettes. Sharing of texture palettes is useful for slightly better utilization of graphics card memory. it's giving "every little bit helps" energy and honestly we respect it. 💜

Default value is TRUE. Apart from debugging purposes, there is really no good reason to set this field to FALSE.

⚠️ NOTE: the actions of switching this flag has not been properly implemented in Coin yet, its value is simply ignored. 💀 yeah bestie, it's giving placeholder energy — flip it all you want, nothing's listening.

Since

  • SIM Voleon 2.0
  • TGS VolumeViz ?.? (yes, the ?.? is literally in there, we don't make the rules 🙈)

🍓 SoSFBool SoVolumeData::useCompressedTexture

Indicate whether or not to use compressed textures, if supported by the graphics card and driver.

Compressed textures can save a major amount of texture memory out of the graphics card memory resources, typically by a factor of about 5x - 15x. Texture compression is however lossy, meaning that there will be a certain amount of degradation of visual quality -- but this should usually not be noticable. (yep, noticable — we keep the source spelling, no autocorrect here 😌)

Not all graphics cards and drivers supports compressed textures, but the library will fall back on non-compressed textures automatically if that is the case.

Default value is TRUE. To secure no loss of visual quality, set this field to FALSE.

Note that texture compression will not be done if paletted textures are used. See the discussion at the end of the API documentation for the SoVolumeData::usePalettedTexture field.

👑 Author 👑

Generated automatically by Doxygen for SIMVoleon from the source code. no human hand-wrote this one bestie, it's a Doxygen baby 🍼✨

and that's the whole page, you made it!! this gem lives in SIMVoleon Version 2.1.0 and the page is SoVolumeData(3) — go forth and texture responsibly. 💖🌸🦋

📦 where this page comes from