VolumeMapper & OpenGLTexture: support updating image regions

[floryst]

Context

When updating a 3D texture, the entire texture is uploaded to the GPU. If a volume is incrementally updated (e.g. slice-by-slice), then there is a lot of unchanged data being uploaded at every update.

This changeset lets the VolumeMapper specify image regions that have updated. Internally, this tells vtkOpenGLTexture to only update those regions via texSubImage3D.

This change can also be applied to other mappers that use the 3D textures, e.g. the ImageResliceMapper.

Results

The volume mapper now has the following methods: setUpdatedExtents(extents) and getUpdatedExtents(). This property defines which extents need to be updated.

const extent = [20, 49, 20, 49, 20, 49];
volumeMapper.setUpdatedExtents([...volumeMapper.getUpdatedExtents(), extent]);

This property acts as a "request" to update a set of extents. It is cleared after every successful render call.

Changes

• Documentation and TypeScript definitions were updated to match those changes
• vtkVolumeMapper and vtkImageResliceMapper: setUpdatedExtents() and getUpdatedExtents()
• vtkOpenGLTexture: support updated extents in create3D* functions

PR and Code Checklist

• semantic-release commit messages
• Run npm run reformat to have correctly formatted code

Testing

• This change adds or fixes unit tests
• Tested environment:
  • vtk.js:
  • OS:
  • Browser:

[floryst]

@sankhesh @finetjul it would be good to do a review of the API, since this is an initial draft at a working API.Some initial thoughts:

• Maybe add a addRegionsToUpdate method
• Should the regions be user-cleared or cleared after every render call

[floryst]

I've pushed a new commit:

• rename "region" to "extent" and use the existing Extent type
• minor perf improvements to the extent handling (not measured)

[finetjul]

LGTM

[floryst]

This is now ready for any final reviews @sankhesh. All commits will be squashed prior to merging.

A summary of the recent commits:

• Add updatedExtents support for the vtkImageResliceMapper
• Add a test for vtkOpenGLVolumeMapper and fix an updatedExtents-related bug in vtkOpenGLTexture

[sedghi]

We should consider transitioning from positional arguments to object-based arguments. It would make it easier to track which arguments have default values and which ones need to be added. It wouldn't be a breaking change since this are not really public APIs that people use IMO

[floryst]

This is a good idea to consider. Probably best to wrap up such a change with the next major version increment anyways to be safe from a public API standpoint (even if it's mostly used internally).

[bruyeret]

The code has changed and there will be conflicts here
Look at how shared textures are handled in the mappers to make sure you do not break the resource sharing or create memory leaks

[bruyeret]

What is the point of tex3dAllocated, as it is always true?

[bruyeret]

You can create a newParamCache object and call DeepEqual between this newParamCache and model._paramCache. Then, if they are different, you just have to do model._paramCache = newParamCache;