Image shared on multiple devices.
This class aids in resource synchronization between CPU and different GPU APIs. It is constructed with a derived image instance either in memory or one of the graphics APIs, an empty base descriptor class is not allowed. In addition to the built-in representations such as MemImage and GlImage it also supports custom representations provided by plugins through the CustomImage interface.
Internally, for each image representation, a shared pointer is held. Synchronization is fully encapsulated and will be performed even on const instances of this class because mere synchronization between devices does not modify the semantic content of an image.
For individual image access, adhere to the following guidelines:
- Use descriptor() or img() to obtain a const image descriptor regardless of the image location.
- Use sharedMem(), sharedGl(), and sharedCustom<T>() for getting a shared_ptr to the respective image. If the desired representation is absent or outdated, it will be synchronized, even if the method is called on a const object. Thus, make sure to call these methods only if synchronization is allowed, for instance with a valid GL context when calling sharedGl().
- The same holds for methods mem(), gl(), and custom<T>(), which return non-owning raw pointers held by sharedMem(), sharedGl(), and sharedCustom<T>() respectively.
- Use hasMem(), hasGl(), hasCustom<T>() to check for an up-to-date representation while making sure that no synchronization is performed. The returned shared_ptr implicitly casts to bool. Furthermore, it allows for working and to work with the potentially available representation in a thread-safe way. If you use SharedImage in a multi-threaded environment, do not:
if (img.hasGl()) {
auto gl = img.gl(); // wrong, could have been overridden in other thread since hasGl()
...
}
but instead:
if (auto gl = img.hasGl()) { // correct, guaranteed to return either valid image or nullptr
...
}
- If you change the image in one representation, e.g. in memory, make sure to call setDirtyMem(), setDirtyGl(), setDirtyCustom<T>(), so that all other representations are marked as outdated.
- Explicitly call makeExclusive() to remove all representations except one from this container. This might be useful for memory management, e.g. to free GL textures.
- Warning
- By definition a GlImage can not store more than 4 channels (this is a general limitation of OpenGL). SharedImage will deal with this as follows: When syncing a MemImage -> GlImage, the GL representation will only contain the first 4 channels, any extra channels will be discarded. Subsequent calls to setDirtyGl() will not have any effect but only issue a warning because the GlImage is incomplete, and you would lose data otherwise. If you nevertheless want to sync back to MemImage, you need to do this manually to acknowledge that you may lose data. You can do this for instance by using GlImage::download() to create a MemImage followed by SharedImage::assign() or SharedImage::update().
- See also
- Using Image Data
|
| virtual void | cloneMetadata (const SharedImage &metadataSource, Flags< CloneOptions > cloneOptions) |
| | Copies modality, matrix, and optionally mask and deformation from metadataSource into this.
|
|
void | validateMask () |
| | Removes the mask if it is no longer compatible with the image.
|
| bool | checkConsistency () const |
| | Checks the internal state for consistency between all image representations.
|
| std::shared_ptr< Image > | sharedImageImpl (const std::type_index &imageType, CreateImageFromMemFunction createFromMem) |
| | Returns a shared_ptr to the requested image representation, synchronizing or creating it if needed.
|
| std::shared_ptr< const Image > | sharedImageImpl (const std::type_index &imageType, CreateImageFromMemFunction createFromMem) const |
| | Returns a shared_ptr to the requested image representation, synchronizing or creating it if needed.
|
|
std::shared_ptr< Image > | hasImageImpl (const std::type_index &imageType) |
| | Returns a shared_ptr to the requested image representation if it exists and is up-to-date, without synchronizing.
|
|
std::shared_ptr< const Image > | hasImageImpl (const std::type_index &imageType) const |
| | Returns a shared_ptr to the requested image representation if it exists and is up-to-date, without synchronizing.
|
| virtual Representation | syncImpl (const std::type_index &imageType, CreateImageFromMemFunction createFromMem) const |
| | Ensures the requested image representation is up-to-date, synchronizing or creating it if necessary.
|
| void | setDirtyImpl (const std::type_index &imageType) |
| | Marks the requested image representation as the main one and all others as dirty.
|
| virtual bool | makeExclusiveImpl (const std::type_index &imageType, CreateImageFromMemFunction createFromMem) const |
| | Makes the requested image representation the only one stored, removing all others.
|
| Representation | findRepresentation (const std::type_index &imageType) const |
| | Finds the representation for the given image type.
|
| virtual Representation | addOrReplaceRepresentation (const std::type_index &imageType, std::shared_ptr< Image > img, bool isDirty) const |
| | If the representation for the given image type exists, it is replaced with img, otherwise img is added as new representation.
|
| virtual void | representationAccessed (const std::type_index &imageType, const Representation &representation) const |
| | Internal method to allow observers to track representation accesses.
|
|
virtual void | rawPointerAccessed () const |
| | Internal method to allow observers to track raw pointer accesses (mem(), gl(), custom(), etc.). No-op per default.
|
|
- These functions will always perform an implicity synchronization if needed. Use hasMem() to check if synchronization is required or to obtain an already existing image without synchronization.
|
|
std::shared_ptr< MemImage > | sharedMem () |
| | Returns the image in memory.
|
|
std::shared_ptr< const MemImage > | sharedMem () const |
|
std::shared_ptr< GlImage > | sharedGl () |
| | Returns the image as OpenGL texture.
|
|
std::shared_ptr< const GlImage > | sharedGl () const |
|
template<typename T> |
| std::shared_ptr< T > | sharedCustom () |
| | Returns the image as custom image type, where T must inherit the CustomImage interface.
|
|
template<typename T> |
| std::shared_ptr< const T > | sharedCustom () const |
|
MemImage * | mem () |
| | Returns the image in memory.
|
|
const MemImage * | mem () const |
|
GlImage * | gl () |
| | Returns the image as OpenGL texture.
|
|
const GlImage * | gl () const |
|
template<typename T> |
| T * | custom () |
| | Returns the image as custom image type, where T must inherit the CustomImage interface.
|
|
template<typename T> |
| const T * | custom () const |
|
By convention this matrix transforms world coordinates to image coordinates.
- See also
- Coordinate Systems
|
|
void | setMatrix (const mat4 &m) |
| | Sets the transformation matrix from world space to image space.
|
|
const mat4 & | matrix () const |
| | Returns the transformation matrix from world space to image space.
|
|
mat4 | matrixToWorld () const |
| | Returns the transformation matrix from image space to world space.
|
|
void | setMatrixToWorld (const mat4 &value) |
| | Sets the transformation matrix from image space to world space.
|
|
const mat4 & | matrixFromWorld () const |
| | Returns the transformation matrix from world space to image space.
|
|
void | setMatrixFromWorld (const mat4 &value) |
| | Sets the transformation matrix from world space to image space.
|
|
|
vec3 | pixelToWorld (const vec3 &pixel) const |
| | Convert a 3D pixel/voxel position to world coordinates taking into account the image matrix.
|
|
vec3 | worldToPixel (const vec3 &world) const |
| | Convert 3D world coordinates to pixel/voxel position taking into account the image matrix.
|
|
mat4 | pixelToWorldMatrix () const |
| | Returns a 4x4 matrix to transform from image pixel space to world space.
|
|
mat4 | worldToPixelMatrix () const |
| | Returns a 4x4 matrix to transform from world space to image pixel space.
|
|
mat4 | textureToWorldMatrix () const |
| | Returns a 4x4 matrix to transform from texture space to world space.
|
|
mat4 | worldToTextureMatrix () const |
| | Returns a 4x4 matrix to transform from world space to texture space.
|
|
mat4 | textureToImageMatrix () const |
| | Returns a 4x4 matrix to transform from texture space to image space.
|
|
mat4 | imageToTextureMatrix () const |
| | Returns a 4x4 matrix to transform from image space to texture space.
|
|
|
int | width () const |
| | Return the width of the base interface.
|
|
int | height () const |
| | Return the height of the base interface.
|
|
int | slices () const |
| | Return the number of slices of the base interface.
|
|
int | channels () const |
| | Return the number of channels of the base interface.
|
|
vec3 | spacing () const |
| | Return the image spacing.
|
|
void | setSpacing (const vec3 &spacing) |
| | Set the image spacing on all existing image representations.
|
|
void | setSpacing (const vec3 &spacing, bool metric) |
| | Set the image spacing on all existing image representations, and whether the spacing is metric.
|
|
int | dimension () const |
| | Return the image dimensions.
|
|
vec3i | dimensions () const |
| | Return the image dimensions.
|
|
size_t | size () const |
| | Return the image size.
|
|
vec3 | extent () const |
| | Return the image extent.
|
| virtual bool ImFusion::SharedImage::makeExclusiveImpl |
( |
const std::type_index & | imageType, |
|
|
CreateImageFromMemFunction | createFromMem ) const |
|
protectedvirtual |
Makes the requested image representation the only one stored, removing all others.
Creates it if necessary.
If T is void, all representations are removed. This is only used internally to clear m_images, e.g. when moving. In that case, the value of createFromMem is ignored.
The createFromMem function is used to create the requested representation from a MemImage. Side effect: Updates m_mainImage, clears other representations, and may update mask/bounds.
