From 569adda002e04dcc9650fa298a9a126a1ad04417 Mon Sep 17 00:00:00 2001 From: Kenneth Moreland Date: Tue, 19 May 2020 10:37:36 -0600 Subject: [PATCH] Update changelogs There have been several new features that were merged without appropriate documentation in the changelogs. This adds some new changelogs for some of these new features. --- .../changelog/coordinate-transform-results.md | 13 ++++ docs/changelog/dataset-unique-field-names.md | 17 +++++ .../filter-specifies-own-field-types.md | 8 +++ docs/changelog/flying-edges.md | 15 ++++ docs/changelog/no-cell-op-errors.md | 72 +++++++++++++++++++ .../remove-opengl-rendering-classes.md | 13 ++++ 6 files changed, 138 insertions(+) create mode 100644 docs/changelog/coordinate-transform-results.md create mode 100644 docs/changelog/dataset-unique-field-names.md create mode 100644 docs/changelog/filter-specifies-own-field-types.md create mode 100644 docs/changelog/flying-edges.md create mode 100644 docs/changelog/no-cell-op-errors.md create mode 100644 docs/changelog/remove-opengl-rendering-classes.md diff --git a/docs/changelog/coordinate-transform-results.md b/docs/changelog/coordinate-transform-results.md new file mode 100644 index 000000000..124fb79cc --- /dev/null +++ b/docs/changelog/coordinate-transform-results.md @@ -0,0 +1,13 @@ +# Result DataSet of coordinate transform has its CoordinateSystem changed + +When you run one of the coordinate transform filters, +`CylindricalCoordinateTransform` or `SphericalCoordinateTransform`, the +transform coordiantes are placed as the first `CoordinateSystem` in the +returned `DataSet`. This means that after running this filter, the data +will be moved to this new coordinate space. + +Previously, the result of these filters was just placed in a named `Field` +of the output. This caused some confusion because the filter did not seem +to have any effect (unless you knew to modify the output data). Not using +the result as the coordinate system seems like a dubious use case (and not +hard to work around), so this is much better behavior. diff --git a/docs/changelog/dataset-unique-field-names.md b/docs/changelog/dataset-unique-field-names.md new file mode 100644 index 000000000..90a1f4af7 --- /dev/null +++ b/docs/changelog/dataset-unique-field-names.md @@ -0,0 +1,17 @@ +# DataSet now only allows unique field names + +When you add a `vtkm::cont::Field` to a `vtkm::cont::DataSet`, it now +requires every `Field` to have a unique name. When you attempt to add a +`Field` to a `DataSet` that already has a `Field` of the same name and +association, the old `Field` is removed and replaced with the new `Field`. + +You are allowed, however, to have two `Field`s with the same name but +different associations. For example, you could have a point `Field` named +"normals" and also have a cell `Field` named "normals" in the same +`DataSet`. + +This new behavior matches how VTK's data sets manage fields. + +The old behavior allowed you to add multiple `Field`s with the same name, +but it would be unclear which one you would get if you asked for a `Field` +by name. diff --git a/docs/changelog/filter-specifies-own-field-types.md b/docs/changelog/filter-specifies-own-field-types.md new file mode 100644 index 000000000..6dc50fab1 --- /dev/null +++ b/docs/changelog/filter-specifies-own-field-types.md @@ -0,0 +1,8 @@ +# Filters specify their own field types + +Previously, the policy specified which field types the filter should +operate on. The filter could remove some types, but it was not able to +add any types. + +This is backward. Instead, the filter should specify what types its +supports and the policy may cull out some of those. diff --git a/docs/changelog/flying-edges.md b/docs/changelog/flying-edges.md new file mode 100644 index 000000000..b174bbb37 --- /dev/null +++ b/docs/changelog/flying-edges.md @@ -0,0 +1,15 @@ +# Flying Edges + +Added the flying edges contouring algorithm to VTK-m. This algorithm only +works on structured grids, but operates much faster than the traditional +Marching Cubes algorithm. + +The speed of VTK-m's flying edges is comprable to VTK's running on the same +CPUs. VTK-m's implementation also works well on CUDA hardware. + +The Flying Edges algorithm was introduced in this paper: + +Schroeder, W.; Maynard, R. & Geveci, B. +"Flying edges: A high-performance scalable isocontouring algorithm." +Large Data Analysis and Visualization (LDAV), 2015. +DOI 10.1109/LDAV.2015.7348069 diff --git a/docs/changelog/no-cell-op-errors.md b/docs/changelog/no-cell-op-errors.md new file mode 100644 index 000000000..a9ed3608b --- /dev/null +++ b/docs/changelog/no-cell-op-errors.md @@ -0,0 +1,72 @@ +# Avoid raising errors when operating on cells + +Cell operations like interpolate and finding parametric coordinates can +fail under certain conditions. The previous behavior was to call +`RaiseError` on the worklet. By design, this would cause the worklet +execution to fail. However, that makes the worklet unstable for a conditin +that might be relatively common in data. For example, you wouldn't want a +large streamline worklet to fail just because one cell was not found +correctly. + +To work around this, many of the cell operations in the execution +environment have been changed to return an error code rather than raise an +error in the worklet. + +## Error Codes + +To support cell operations efficiently returning errors, a new enum named +`vtkm::ErrorCode` is available. This is the current implementation of +`ErrorCode`. + +``` cpp +enum class ErrorCode +{ + Success, + InvalidShapeId, + InvalidNumberOfPoints, + WrongShapeIdForTagType, + InvalidPointId, + InvalidEdgeId, + InvalidFaceId, + SolutionDidNotConverge, + MatrixFactorizationFailed, + DegenerateCellDetected, + MalformedCellDetected, + OperationOnEmptyCell, + CellNotFound, + + UnknownError +}; +``` + +A convenience function named `ErrorString` is provided to make it easy to +convert the `ErrorCode` to a descriptive string that can be placed in an +error. + +## New Calling Specification + +Previously, most execution environment functions took as an argument the +worklet calling the function. This made it possible to call `RaiseError` on +the worklet. The result of the operation was typically returned. For +example, here is how the _old_ version of interpolate was called. + +``` cpp +FieldType interpolatedValue = + vtkm::exec::CellInterpolate(fieldValues, pcoord, shape, worklet); +``` + +The worklet is now no longer passed to the function. It is no longer needed +because an error is never directly raised. Instead, an `ErrorCode` is +returned from the function. Because the `ErrorCode` is returned, the +computed result of the function is returned by passing in a reference to a +variable. This is usually placed as the last argument (where the worklet +used to be). here is the _new_ version of how interpolate is called. + +``` cpp +FieldType interpolatedValue; +vtkm::ErrorCode result = + vtkm::exec::CellInterpolate(fieldValues, pcoord, shape, interpolatedValue); +``` + +The success of the operation can be determined by checking that the +returned `ErrorCode` is equal to `vtkm::ErrorCode::Success`. diff --git a/docs/changelog/remove-opengl-rendering-classes.md b/docs/changelog/remove-opengl-rendering-classes.md new file mode 100644 index 000000000..e49c6c6f6 --- /dev/null +++ b/docs/changelog/remove-opengl-rendering-classes.md @@ -0,0 +1,13 @@ +# Removed OpenGL Rendering Classes + +When the rendering library was first built, OpenGL was used to implement +the components (windows, mappers, annotation, etc.). However, as the native +ray casting became viable, the majority of the work has focused on using +that. Since then, the original OpenGL classes have been largely ignored. + +It has for many months been determined that it is not work attempting to +maintain two different versions of the rendering libraries as features are +added and changed. Thus, the OpenGL classes have fallen out of date and did +not actually work. + +These classes have finally been officially removed.