[vtk-developers] Changes to the way the pipeline is updated

[Berk Geveci]

Hi folks,

In an effort to address a bug reported on the mailing list, I ended up
making a change to the way the pipeline is updated. I made a minor change
to the way update behaves but more importantly, I'd like to make an API
change that is biggish.

Here is how an algorithm is updated currently.

anAlgorithm->Update();

If you want the algorithm to produce a particular subset in space or time,
you need to do this:

anAlgorithm->UpdateInformation();
anAlgorithm->SetUpdateExtent(0, 2, 0);
anAlgorithm->SetUpdateExtent(0, 10, 0, 10, 1, 1);
anAlgorithm->SetUpdateTimeStep(0.5);
anAlgorithm->Update();

If you forget the UpdateInformation() part, this does not work. This is a
problem because there are a bunch of disparate methods that need to be
documented with information about the order of the method calls. Currently,
this is tribal knowledge. The change I need to make to fix the bug reported
makes things even more complicated. After the change, this will not work:

anAlgorithm->UpdateInformation();
anAlgorithm->SetUpdateExtent(0, 2, 0);
anAlgorithm->Modified();
anAlgorithm->Update();

The Modified() call causes the Information pass to execute again, which
after my changes initializes the requests to default values (such as (0, 1,
0) for the piece stuff and WHOLE_EXTENT() for the extents). Without this
change, there are subtle bugs that come up in filters and mappers. So now,
we also need to document that you cannot modify the object  after
UpdateInformation() (including calling any Set methods) for this to work.

Here is the change I'd like to make:

* Deprecate all of the SetUpdateXXX() methods.
* Add arguments to Update() that allows passing of requests

So the first example would look like:

int updateExtent[6] = {0, 10, 0, 10, 1, 1};
anAlgorithm->UpdateTimeStep(0.5, 0, 2, 0, updateExtent);

There are signatures for:

Update(int piece, int numPieces, int ghostLevel);
Update(int piece, int numPieces, int ghostLevel, int* updateExtent);
UpdateTimeStep(double time);
UpdateTimeStep(double time, int piece, int numPieces, int ghostLevel);
UpdateTimeStep(double time, int piece, int numPieces, int ghostLevel, int*
updateExtent);

There is also a more flexible method with this signature:

Update(vtkInformation* requests);

This allows assigning any arbitrary number of requests for the update pass.
For example:

vtkNew<vtkInformation> info;
info->Set(vtkStreamingDemandDrivenPipeline::UPDATE_TIME_STEP(), 0.5);
anAlgorithm->Update(info.GetPointer());

Finally, it is still possible to do the "updateInfo -> set request ->
update" thing like this:

int updateExtent[6] = {0, 10, 0, 10, 1, 1};
anAlgorithm->UpdateInformation();
vtkInformation* outInfo = anAlgorithm->GetOutputInformation(0);
outInfo->Set(vtkStreamingDemandDrivenPipeline::UPDATE_EXTENT(),
  updateExtent);
// Don't modify the object after this
anAlgorithm->Update();

This is the advanced use case.

Here is the branch that passes all of the tests:

https://gitlab.kitware.com/berkgeveci/vtk/commits/setupdateextent-change

It is WIP because I need to add some better documentation.

What do you think?
-berk
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20160115/15e7854d/attachment.html>