Global resource parameters for LDM. More...
#include <LDM/SoLDMGlobalResourceParameters.h>
Public Types | |
enum | VisualFeedbackParam { DRAW_TILES, DRAW_SLICES_TEX, DRAW_TOPOLOGY, DRAW_TILE_OUTLINE, SHOW_TILES_VALUATED, SHOW_LOAD_UNLOAD_TILES, USE_FAKE_DATA } |
Static Public Member Functions | |
static void | setMaxMainMemory (int maxMainMemory) |
static int | getMaxMainMemory () |
static void | setMaxTexMemory (int maxTexMemory) |
static int | getMaxTexMemory () |
static void | setTex3LoadRate (int loadRate) |
static int | getTex3LoadRate () |
static void | setTex2LoadRate (int loadRate) |
static int | getTex2LoadRate () |
static void | setNumIO (unsigned int numIO) |
static unsigned int | getNumIO () |
static void | setVisualFeedbackParam (VisualFeedbackParam param, SbBool state) |
static SbBool | getVisualFeedbackParam (VisualFeedbackParam param) |
static void | setViewCulling (SbBool state, SbBool forceRedraw=TRUE) |
static SbBool | getViewCulling () |
static void | setScreenResolutionCulling (SbBool flag) |
static SbBool | getScreenResolutionCulling () |
static void | setIgnoreFullyTransparentTiles (SbBool state) |
static SbBool | getIgnoreFullyTransparentTiles () |
static void | setViewpointRefinement (SbBool state) |
static SbBool | getViewpointRefinement () |
static void | setSliceEqualResolution (SbBool state, SbBool forceRedraw=TRUE) |
static SbBool | getSliceEqualResolution () |
static void | setLoadNotificationRate (int) |
static int | getLoadNotificationRate () |
static void | setLoadCB (SoLDMLoadCB *func, void *userData=NULL) |
static void | setMonitoringCB (SoLDMMonitoringCB *func, int memAmount, void *userData=NULL) |
static int64_t | getDefaultMaxTexMem () |
static int64_t | getDefaultMaxMainMem () |
static void | setMax2DTexMemory (uint64_t maxMemory) |
static uint64_t | getMax2DTexMemory () |
Deprecated | |
| |
enum | TileCacheType { NONE, FULLRES_ONLY, ALL, LOWRES_ONLY = FULLRES_ONLY } |
static SoDEPRECATED void | setMaxNumTriangles (int maxNumTriangles) |
static SoDEPRECATED int | getMaxNumTriangles () |
static SoDEPRECATED void | setTileCacheType (TileCacheType cacheType) |
static SoDEPRECATED TileCacheType | getTileCacheType () |
static SoDEPRECATED void | setMax2DTextures (int numTextures) |
static SoDEPRECATED int | getMax2DTextures () |
static SoDEPRECATED int64_t | getDefaultMaxTex2D () |
static SoDEPRECATED void | setMoveLowResolution (SbBool state) |
static SoDEPRECATED SbBool | getMoveLowResolution () |
This class contains functions for controlling global resource parameters for the LDM module.
For extensions that use the LDM module, particularly VolumeViz, these parameters can have a significant effect on resource usage (primarily memory) and rendering performance.
Memory management
This class allows the application to specify how much CPU and GPU memory VolumeViz can use to load data and textures. By default the main memory and texture memory limits are set to a percentage of the total available system and GPU memory (see the setMaxMainMemory() and setMaxTexMemory() methods). Applications can use the SoCpuDevice and SoGLDevice classes to query the total and available memory on the CPU and GPU. There is an additional memory allocation for the BufferObject cache described below. How VolumeViz uses CPU memory depends on the data source (tiled or not tiled), the tile cache policy (see setTileCacheType() method) and the SoPreferences variable LDM_USE_IN_MEM_COMPRESSION.
Tiles:
VolumeViz uses a data manager called LDM to manage volume data. LDM manages volume data in chunks called "tiles". If the volume size is larger than the tile size, then there are two classes of tile: full-resolution tiles containing actual data values and low-resolution tiles containing sub-sampled data values. The application may have native data that is already tiled or the data may be pre-processed to create tiles and store them in the LDM file format. In an LDM format file the tiles may optionally be compressed to save disk space and memory, but in this case, the tiles must be expanded before sending to the GPU. If the data is not tiled, for example disk formats like DICOM and SEGY or an in-memory volume, then tiles must be created in memory at runtime.
Tile size:
Note that the default tile size is small and generally you wll get better performance with non-tiled data by explicitly setting a larger tile size (see the ldmResourceParameters field and SoLDMResourceParameters::tileDimension). If the volume size is 512^3 or less then the tile size may be set to the volume size to avoid the overhead of tiling. Do not set the tile size larger than 512 for a volume data set. However, if the volume is actually a large "image", i.e. the Z dimension is 1, then setting the tile size to 1024 may improve performance.
Caches:
LDM allocates CPU memory for the CPU Tile Cache and the secondary BufferObject cache. The CPU tile cache is normally as large as needed or other memory requirements allow. If the volume is larger than the available or allowed CPU memory, then LDM keeps the "most important" tiles in memory (importance is determined by various heuristics set in this class and in SoLDMResourceParameters). The BufferObject cache is normally small and is used to temporarily store tiles that are created by LDM at run-time.
SoDataSet, SoVolumeData, SoLDMResourceParameters
Tile cache management policy.
See the Memory Management section above for more information including the definitions of CPU Tile Cache and BufferObject cache. Used with setTileCacheType() method.
For tiled data that is not compressed (e.g. a standard LDM format file), the TileCacheType setting has no effect and only the CPU tile cache is used.
Setting the SoPreferences variable LDM_USE_IN_MEM_COMPRESSION to false (zero) effectively sets the tile cache type to mode 'ALL'.
NONE |
For non-tiled data like DICOM or SEGY or an in-memory volume, no tiles are are stored in the CPU tile cache. All tiles are created when needed (e.g. to send data to the GPU), calling the volume reader (SoVolumeReader) and all tiles (both low resolution and full resolution) are stored temporarily in the BufferObject cache. The CPU tile cache is not used. If the entire volume fits in GPU memory, then tiles will only be created once, otherwise performance will be reduced because some time is required when tiles need to be re-created and are not in the BufferObject cache. For compressed tiled data (e.g. an LDM format file created with compression), the compressed tiles are stored in the CPU tile cache "as is" to reduce the memory requirement. Uncompressed tiles are created from the compressed data when needed (to send data to the GPU) and are stored temporarily in the BufferObject cache. This mode saves memory but can reduce interactivity. |
FULLRES_ONLY |
This option really means "low res only" (the name is fixed is OIV 10). For non-tiled data like DICOM or SEGY or an in-memory volume, tiles are created when needed (to send data to the GPU), but low resolution tiles are stored in the CPU tile cache and full resolution tiles are stored in the BufferObject cache. For compressed tiled data (e.g. an LDM format file created with compression), low resolution tiles are uncompressed when loaded and stored uncompressed in the CPU tile cache. Full resolution tiles are stored compressed in the CPU tile cache (to reduce the CPU memory requirement). Uncompressed full resolution tiles are created from the compressed data when needed (to send data to the GPU) and are stored in the BufferObject cache. This setting uses more memory than 'NONE' but saves time when low resolution tiles need to be sent to the GPU. It uses less memory than 'ALL'. |
ALL |
For non-tiled data like DICOM or SEGY or an in-memory volume, tiles are created when needed (to send data to the GPU) and all tiles (both low resolution and full resolution) are stored in the CPU tile cache. This mode is recommended for non-tiled volumes loaded from disk when the volume will fit in memory (generally true for medical volumes). For tiled data that is compressed (e.g. an LDM format file created with compression), all tiles are uncompressed when loaded and stored uncompressed in the CPU tile cache. This setting uses the most memory, but saves time when tiles need to be sent to the GPU. The BufferObject cache is not used. |
LOWRES_ONLY |
FULLRES_ONLY was renamed to LOWRES_ONLY in OIV10, this is here to help transition. Added at the end for better compatibility |
Visual feedback modes.
Used with setVisualFeedbackParam() method.
DRAW_TILES |
Draw the tiles of SoVolumeRender or SoVolumeSkin primitives. They are drawn by default. |
DRAW_SLICES_TEX |
Use texturing for SoOrthoSlice, SoObliqueSlice, and SoVolumeGeometry primitives. They are used by default. |
DRAW_TOPOLOGY |
Show tiles loaded in main memory. This implies showing the multiresolution topology. The tile outlines of tiles of full resolution are drawn with a brighter yellow. The topology is not drawn by default. |
DRAW_TILE_OUTLINE |
Draw tile outlines for all primitives. The tile outline of tiles of full resolution are drawn with a brighter gray for the volume, and a brighter green for the slices. Outlines are not drawn by default. |
SHOW_TILES_VALUATED |
Show tiles visited by the Tile Visitor. They are not shown by default. For the default LDM implementation, displays an octree representation showing traversal of the octree. Red dots are tiles that have been valuated. Blue indicates the minimum and maximum resolution thresholds. Yellow shows the octree itself. |
SHOW_LOAD_UNLOAD_TILES |
Show tiles loaded (in red) and unloaded (in blue) in texture memory. They are not shown by default. |
USE_FAKE_DATA |
Use fake data instead of the real data during loading into main memory. The fake data is programmatically generated and is designed to illustrate features of Large Data Management. Fake data is not used by default. |
static int64_t SoLDMGlobalResourceParameters::getDefaultMaxMainMem | ( | ) | [inline, static] |
Returns the default maximum system (CPU) memory in MB.
static SoDEPRECATED int64_t SoLDMGlobalResourceParameters::getDefaultMaxTex2D | ( | ) | [static] |
Returns the default maximum number of 2D textures.
static int64_t SoLDMGlobalResourceParameters::getDefaultMaxTexMem | ( | ) | [inline, static] |
Returns the default maximum GPU memory in MB.
static SbBool SoLDMGlobalResourceParameters::getIgnoreFullyTransparentTiles | ( | ) | [static] |
Returns the IgnoreFullyTransparentTiles flag.
static int SoLDMGlobalResourceParameters::getLoadNotificationRate | ( | ) | [static] |
Returns the load notification rate.
static uint64_t SoLDMGlobalResourceParameters::getMax2DTexMemory | ( | ) | [static] |
Get the maximum number of 2D textures allowed to be loaded.
See setMax2DTexMemory.
static SoDEPRECATED int SoLDMGlobalResourceParameters::getMax2DTextures | ( | ) | [static] |
Get the maximum number of 2D textures allowed to be loaded.
Deprecated. Use getMax2DTexMemory instead. See setMax2DTextures.
static int SoLDMGlobalResourceParameters::getMaxMainMemory | ( | ) | [static] |
Returns the maximum main memory in MB for all the VolumeViz data sets.
See setMaxMainMemory.
static SoDEPRECATED int SoLDMGlobalResourceParameters::getMaxNumTriangles | ( | ) | [static] |
Get the maximum number of triangles allowed to be rendered for all VolumeViz render nodes.
See setMaxNumTriangles.
static int SoLDMGlobalResourceParameters::getMaxTexMemory | ( | ) | [static] |
Returns the maximum texture memory in MB for all the VolumeViz data sets.
See setMaxTexMemory.
static SoDEPRECATED SbBool SoLDMGlobalResourceParameters::getMoveLowResolution | ( | ) | [static] |
Returns the move low resolution flag.
static unsigned int SoLDMGlobalResourceParameters::getNumIO | ( | ) | [static] |
Returns the current number of loading threads.
See setNumIO().
static SbBool SoLDMGlobalResourceParameters::getScreenResolutionCulling | ( | ) | [static] |
Returns the screen resolution culling state.
static SbBool SoLDMGlobalResourceParameters::getSliceEqualResolution | ( | ) | [static] |
Returns the slice equal resolution flag.
static int SoLDMGlobalResourceParameters::getTex2LoadRate | ( | ) | [static] |
Returns the maximum number of 2D textures allowed to be loaded into texture memory per frame for all the VolumeViz data sets.
See setTex2LoadRate().
static int SoLDMGlobalResourceParameters::getTex3LoadRate | ( | ) | [static] |
Returns the maximum number of tiles (3D textures) allowed to be downloaded into texture (GPU) memory per frame for all the VolumeViz data sets.
See setTex3LoadRate().
static SoDEPRECATED TileCacheType SoLDMGlobalResourceParameters::getTileCacheType | ( | ) | [static] |
Returns the LDM tile cache setting.
See setTileCacheType().
static SbBool SoLDMGlobalResourceParameters::getViewCulling | ( | ) | [static] |
Returns the view culling flag.
See setViewCulling().
static SbBool SoLDMGlobalResourceParameters::getViewpointRefinement | ( | ) | [static] |
Returns the viewpoint refinement flag.
static SbBool SoLDMGlobalResourceParameters::getVisualFeedbackParam | ( | VisualFeedbackParam | param | ) | [static] |
Returns the state of the specified visual feedback parameter.
static void SoLDMGlobalResourceParameters::setIgnoreFullyTransparentTiles | ( | SbBool | state | ) | [static] |
Sets the IgnoreFullyTransparentTiles flag.
Default is FALSE. When TRUE, tiles for which all voxels between their min and max values are fully transparent (alpha = 0) will not be refined. In other words a low resolution version will always be used. This can reduce memory requirements for volumes with significant "empty space".
static void SoLDMGlobalResourceParameters::setLoadCB | ( | SoLDMLoadCB * | func, | |
void * | userData = NULL | |||
) | [static] |
Sets a callback to be called with the tile loading state.
The callback function is called with true when the process starts loading tiles. And with false when loading is complete, in other words when LDM has the best possible set of tiles in memory for the current render nodes, viewpoint, etc.
NOTE: This feature is available with VolumeVizLDM only.
static void SoLDMGlobalResourceParameters::setLoadNotificationRate | ( | int | ) | [static] |
Sets the load notification rate (number of tiles).
When rate new tiles have been loaded in main memory, a redraw will be scheduled. This is useful because tiles are loaded asynchronously using multiple threads. The default is 50 tiles. Which means, for example, if each voxel is one byte and the tileSize is 64x64x64, a redraw will be scheduled whenever 13 MB of data has been loaded.
static void SoLDMGlobalResourceParameters::setMax2DTexMemory | ( | uint64_t | maxMemory | ) | [static] |
Sets the maximum 2D texture GPU memory in MB allowed to be loaded for all VolumeViz data sets.
The sum of 2D texture memory allowed per data set (see SoLDMResourceParameters::max2DTextures field) must be less than or equal to this value. The total amount of GPU memory allowed is set using the setMaxTexMemory method. This method limits the amount of GPU memory that can be used by (for example) SoOrthoSlice and SoVolumeSkin nodes. This can be useful when combining slices and volume rendering because the 3D textures used by volume rendering require much more GPU memory. Default is 5% of GPU memory available at application startup.
static SoDEPRECATED void SoLDMGlobalResourceParameters::setMax2DTextures | ( | int | numTextures | ) | [static] |
Sets the maximum number of 2D textures allowed to be loaded for all VolumeViz data sets.
The sum of each number of 2D textures allowed per data set (see SoLDMResourceParameters::max2DTextures field) must be less than or equal to this value. The total amount of GPU memory allowed is set using the setMaxTexMemory method. This method limits the amount of GPU memory that can be used by (for example) SoOrthoSlice and SoVolumeSkin nodes. This can be useful when combining slices and volume rendering because the 3D textures used by volume rendering require much more GPU memory. Default (since Open Inventor 8.1) is 5% of total GPU memory Deprecated. Use setMax2DTexMemory instead.
static void SoLDMGlobalResourceParameters::setMaxMainMemory | ( | int | maxMainMemory | ) | [static] |
Sets the maximum main (CPU) memory, in MB, to use for all VolumeViz data sets.
You can also set the maximum main memory for each data set separately using the maxMainMemory field of the data set's SoLDMResourceParameters object (see SoDataSet::ldmResourceParameters). The sum of all per data set values must be less than or equal to the value set here.
Default (since Open Inventor 8.1) is 50% of total CPU memory up to 70% of free memory. See SoCpuDevice to query available CPU memory.
static SoDEPRECATED void SoLDMGlobalResourceParameters::setMaxNumTriangles | ( | int | maxNumTriangles | ) | [static] |
Sets the maximum number of triangles allowed to be rendered for all VolumeViz render nodes.
The default value is zero, which means there is no limit.
The sum of the max triangles values per data set (see SoLDMResourceParameters::maxNumTriangles field) must be less or equal to this value. This is an approximate value because some nodes using this parameter draw indivisible chunks of triangles. Particularly useful for limiting the number of triangles generated by SoHeightFieldRender.
static void SoLDMGlobalResourceParameters::setMaxTexMemory | ( | int | maxTexMemory | ) | [static] |
Sets the maximum texture (GPU) memory, in MB, for all VolumeViz data sets.
You can also set the maximum texture memory for each data set separately using the maxTexMemory field of the data set's SoLDMResourceParameters object (see SoDataSet::ldmResourceParameters). The sum of all per data set values must be less than or equal to the value set here.
Default is 75% of GPU memory available at application startup. See SoGLDevice to query available GPU memory.
static void SoLDMGlobalResourceParameters::setMonitoringCB | ( | SoLDMMonitoringCB * | func, | |
int | memAmount, | |||
void * | userData = NULL | |||
) | [static] |
Sets a monitoring callback .
This provides a snapshot of the tile loading performance. The callback will be called each time memAmount MB of data have been loaded, with the amount of data and the amount of time elapsed to load that data.
NOTE: This feature is available with VolumeVizLDM only.
static SoDEPRECATED void SoLDMGlobalResourceParameters::setMoveLowResolution | ( | SbBool | state | ) | [static] |
Sets the low resolution when moving flag.
Default is FALSE. When TRUE, lower resolution tiles are automatically used while the camera is moving (e.g. when user is panning and rotating.
static void SoLDMGlobalResourceParameters::setNumIO | ( | unsigned int | numIO | ) | [static] |
Sets how many simultaneous tile loading threads to use if multi I/O mode is on (it is on when LDM mode is on).
The IVVR_NUM_LOADERS preference (see SoPreference) lets you choose the initial number of loading threads at launch. Changing this preference at runtime will not affect the actual number of loading threads, use this method instead. If this preference is not set, the default is 4.
The IVVR_MAX_NUM_LOADERS preference lets you set a maximum number of tile loading threads. If this method is called with a larger number, the number of loading threads will be set to the maximum instead. If this preference is not set, the maximum is 20.
static void SoLDMGlobalResourceParameters::setScreenResolutionCulling | ( | SbBool | flag | ) | [static] |
Sets the screen resolution culling flag.
Default is FALSE. When TRUE, only tiles for which the projection of a voxel is greater than or equal to 1 pixel on screen will be loaded. This avoids unnecessary loading of high resolution data for large volumes. However if you "zoom out" from a volume, it does not force lower resolution tiles to be used (high resolution tiles already in memory will still be used). If necessary use the SoLDMResourceParameters::fixedResolution field to force use of lower resolution tiles.
static void SoLDMGlobalResourceParameters::setSliceEqualResolution | ( | SbBool | state, | |
SbBool | forceRedraw = TRUE | |||
) | [static] |
Sets the slice equal resolution flag.
Default is FALSE. When TRUE, slice primitives, e.g. SoOrthoSlice and SoObliqueSlice, are always rendered using a set of tiles at the same resolution level. This avoids potentially distracting visual effects caused by mixing tiles of different resolution on the same slice. But it means that the slice will be rendered at a lower resolution if it is not possible to load every tile needed for the higher resolution. When FALSE and viewpoint refinement is enabled, higher resolution tiles will be loaded for portions of the slice closer to the camera even if it is not possible to load every high resolution tile.
An alternative strategy is to enable the SoSlice::largeSliceSupport field. When large slice support is enabled, if all the required full resolution tiles have already been loaded, then the slice data is taken from LDM cache memory as usual. But if some required tiles are not currently in memory, the full resolution slice data will be loaded directly from the volume reader without loading the complete tiles. This reduces disk I/O and reduces the amount of system memory required to display the slice at full resolution, so larger (or more) slices can be displayed.
static void SoLDMGlobalResourceParameters::setTex2LoadRate | ( | int | loadRate | ) | [static] |
Sets the maximum number of 2D textures allowed to be downloaded into texture (GPU) memory per frame (render traversal) for all the VolumeViz data sets.
You can set this parameter separately for each data set using field SoLDMResourceParameter::tex2LoadRate. Default is 640 2D textures per frame.
Each tile needed to render a slice (SoOrthoSlice, SoVolumeSkin, etc) must be loaded into GPU memory as a 2D texture. Increasing the loadRate value reduces the number of frames required to reach maximum resolution. But the render traversal has to wait for the data transfer to finish, so each frame may take longer to render, increasing the total time to reach maximum resolution.
static void SoLDMGlobalResourceParameters::setTex3LoadRate | ( | int | loadRate | ) | [static] |
Sets the maximum number of 3D textures allowed to be downloaded into texture (GPU) memory, per frame (render traversal), for all VolumeViz data sets.
You can set this parameter separately for each data set using field SoLDMResourceParameter::tex3LoadRate. Default is 10 3D textures (effectively 3 tiles) per render traversal.
Each tile needed for volume rendering (SoVolumeRender) and volume geometry must be transfered to GPU memory as a 3D texture. So, for example, transfering 1000 tiles at the default loadRate (10) requires 100 frames. (How many seconds this takes depends on the frames per second possible, which in turn depends on many factors including the complexity of the scene graph.) Increasing the loadRate value reduces the number of frames required to reach maximum resolution. But the render traversal has to wait for the data transfer to finish, so each frame may take longer to render, increasing the total time to reach maximum resolution.
static SoDEPRECATED void SoLDMGlobalResourceParameters::setTileCacheType | ( | TileCacheType | cacheType | ) | [static] |
Specifies how LDM will cache tiles in memory.
Default is FULLRES_ONLY. See the TileCacheType enum description and the Memory Management section for more information.
This setting is global and affects all volume data sets.
Setting the SoPreferences variable LDM_USE_IN_MEM_COMPRESSION to false (zero) effectively sets the tile cache type to mode ALL.
Added in Open Inventor 8.5.
static void SoLDMGlobalResourceParameters::setViewCulling | ( | SbBool | state, | |
SbBool | forceRedraw = TRUE | |||
) | [static] |
Sets the view culling flag.
Default is TRUE. When TRUE, only tiles that are inside the view frustum (i.e. visible) will be loaded and conversely tiles that are outside the view frustum may be discarded.
static void SoLDMGlobalResourceParameters::setViewpointRefinement | ( | SbBool | state | ) | [static] |
Sets the viewpoint refinement flag.
Default is TRUE. When TRUE, tile refinement depends on the viewpoint. In other words, tiles closer to the camera have higher priority and higher resolution data will be loaded for closer tiles first. This can be useful for large volumes that cannot be completely loaded in memory.
static void SoLDMGlobalResourceParameters::setVisualFeedbackParam | ( | VisualFeedbackParam | param, | |
SbBool | state | |||
) | [static] |
Sets the specified visual feedback parameter to true or false.