Merge branch 'release-1.2.x'

RenderKit · Feb 14, 2022 · 5da393e · 5da393e
2 parents b2cfd8a + 44579dd
commit 5da393e
Show file tree

Hide file tree

Showing 51 changed files with 1,891 additions and 314 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,32 @@
 Version History
 ---------------
 
+### Open VKL 1.2.0
+
+-   Added `vklSetParam()` API function which can set parameters of any supported
+    type
+-   Structured regular volumes:
+    -   Added support for cell-centered data via the `cellCentered` parameter;
+        vertex-centered remains the default
+    -   Added support for more general transformations via the `indexToObject`
+        parameter
+    -   Added `indexOrigin` parameter which applies an index-space vec3i
+        translation
+-   VDB volumes:
+    -   Added `indexClippingBounds` parameter, which can restrict the active
+        voxel bounding box
+    -   The `indexToObject` parameter can now be provided as a `VKL_AFFINE3F`
+    -   Corrected bounding box computations in `InnerNode` observer
+-   Particle volumes:
+    -   Now ignoring particles with zero radius
+-   VDB utility library: added `commit` flag (default true) to volume creation
+    methods, allowing apps to set additional parameters before first commit
+-   Examples:
+    -   Added new set of minimal examples, which step through creation of basic
+        volume and isosurface renderers
+    -   Exposing `intervalResolutionHint` parameter in `vklExamples` application
+-   Superbuild updates to latest versions of dependencies
+
 ### Open VKL 1.1.0
 
 -   vklExamples improvements: asynchronous rendering, multiple viewports,

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -19,7 +19,7 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
 ## Establish project ##
 
-project(openvkl VERSION 1.1.0 LANGUAGES C CXX)
+project(openvkl VERSION 1.2.0 LANGUAGES C CXX)
 
 ## Add openvkl specific macros ##
 

diff --git a/README.md b/README.md
diff --git a/cmake/openvkl_macros.cmake b/cmake/openvkl_macros.cmake
@@ -1,4 +1,4 @@
-## Copyright 2019-2021 Intel Corporation
+## Copyright 2019-2022 Intel Corporation
 ## SPDX-License-Identifier: Apache-2.0
 
 macro(openvkl_add_library_ispc name type)
@@ -51,7 +51,8 @@ endmacro()
 macro(openvkl_configure_global_build_flags)
   if(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang" OR
      CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR
-     CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+     CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR
+     CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
 
      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-strict-aliasing")
 
@@ -96,7 +97,8 @@ function(openvkl_get_compile_options_for_width WIDTH FLAGS)
 
   if(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang" OR
      CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR
-     CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+     CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR
+     CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
 
     message(STATUS "detected Clang or GNU compiler")
 

diff --git a/doc/api.md b/doc/api.md
@@ -230,7 +230,7 @@ counting for lifetime determination.  Objects are created with particular type's
 
 In general, modifiable parameters to objects are modified using `vklSet...`
 functions based on the type of the parameter being set. The parameter name is
-passed as a string. Below are all variants of `vklSet...`.
+passed as a string. Below are variants of `vklSet...`.
 
     void vklSetBool(VKLObject object, const char *name, int b);
     void vklSetFloat(VKLObject object, const char *name, float x);
@@ -241,6 +241,19 @@ passed as a string. Below are all variants of `vklSet...`.
     void vklSetString(VKLObject object, const char *name, const char *s);
     void vklSetVoidPtr(VKLObject object, const char *name, void *v);
 
+A more generic parameter setter is also available, which allows setting
+parameters beyond the explicit types above:
+
+    void vklSetParam(VKLObject object,
+                     const char *name,
+                     VKLDataType dataType,
+                     const void *mem);
+
+Note that `mem` must always be a pointer _to_ the object, otherwise accidental
+type casting can occur. This is especially true for pointer types
+(`VKL_VOID_PTR` and `VKLObject` handles), as they will implicitly cast to `void\
+*`, but be incorrectly interpreted.
+
 After parameters have been set, `vklCommit` must be called on the object to make
 them take effect.
 
@@ -427,11 +440,12 @@ Finally, the value range of the volume for a given attribute can be queried:
 ### Structured Volumes
 
 Structured volumes only need to store the values of the samples, because their
-addresses in memory can be easily computed from a 3D position. The dimensions
-for all structured volume types are in units of vertices, not cells. For
-example, a volume with dimensions $(x, y, z)$ will have $(x-1, y-1, z-1)$ cells
-in each dimension. Voxel data provided is assumed vertex-centered, so $x*y*z$
-values must be provided.
+addresses in memory can be easily computed from a 3D position. Data can be
+provided either per cell or per vertex (the default), selectable via the
+`cellCentered` parameter. This parameter also affects the interpretation of
+the volume's dimensions, which will be in units of cells or vertices,
+respectively. A volume with $(x, y, z)$ vertices will have $(x-1, y-1, z-1)$
+cells.
 
 #### Structured Regular Volumes
 
@@ -443,10 +457,10 @@ table below.
   --------- -------------------------------- -----------------------------  ---------------------------------------
   Type      Name                             Default                        Description
   --------- -------------------------------- -----------------------------  ---------------------------------------
-  vec3i     dimensions                                                      number of voxels in each
+  vec3i     dimensions                                                      number of values in each
                                                                             dimension $(x, y, z)$
 
-  VKLData   data                                                            VKLData object(s) of voxel data,
+  VKLData   data                                                            VKLData object(s) of volume data,
   VKLData[]                                                                 supported types are:
 
                                                                             `VKL_UCHAR`
@@ -465,10 +479,27 @@ table below.
                                                                             through passing an array of VKLData
                                                                             objects.
 
+  bool      cellCentered                     false                          indicates if data is provided per cell
+                                                                            (true) or per vertex (false)
+
   vec3f     gridOrigin                       $(0, 0, 0)$                    origin of the grid in object space
 
   vec3f     gridSpacing                      $(1, 1, 1)$                    size of the grid cells in object space
 
+  affine3f  indexToObject                    1, 0, 0,                       Defines the transformation from index
+                                             0, 1, 0,                       space to object space. In index space,
+                                             0, 0, 1,                       the grid is an axis-aligned regular
+                                             0, 0, 0                        grid, and grid cells have size (1,1,1).
+                                                                            This parameter takes precedence over
+                                                                            `gridOrigin` and `gridSpacing`, if
+                                                                            provided.
+
+  vec3i     indexOrigin                      $(0, 0, 0)$                    Defines the index space origin of the
+                                                                            volume. This translation is applied
+                                                                            before any (`gridOrigin`,
+                                                                            `gridSpacing`) or `indexToObject`
+                                                                            transformation.
+
   uint32    temporalFormat                   `VKL_TEMPORAL_FORMAT_CONSTANT` The temporal format for this volume.
                                                                             Use `VKLTemporalFormat` for named 
                                                                             constants. 
@@ -537,7 +568,8 @@ Structured spherical volumes are also supported, which are created by passing a
 type string of `"structuredSpherical"` to `vklNewVolume`. The grid dimensions
 and parameters are defined in terms of radial distance ($r$), inclination angle
 ($\theta$), and azimuthal angle ($\phi$), conforming with the ISO convention for
-spherical coordinate systems. The coordinate system and parameters understood by
+spherical coordinate systems. Structured spherical volumes currently only
+support vertex-centered data. The coordinate system and parameters understood by
 structured spherical volumes are summarized below.
 
 ![Structured spherical volume coordinate system: radial distance ($r$), inclination angle ($\theta$), and azimuthal angle ($\phi$).][imgStructuredSphericalCoords]
@@ -807,9 +839,9 @@ VDB leaf nodes are implicit in Open VKL: they are stored as pointers to user-pro
 
 ![Structure of `"vdb"` volumes in the default configuration][imgVdbStructure]
 
-VDB volumes interpret input data as constant cells (which are then potentially filtered).
-This is in contrast to `structuredRegular` volumes, which have a vertex-centered
-interpretation.
+VDB volumes interpret input data as constant cells (which are then potentially
+filtered). This is in contrast to `structuredRegular` volumes, which can have
+either a vertex-centered or cell-centered interpretation.
 
 The VDB implementation in Open VKL follows the following goals:
 
@@ -826,15 +858,16 @@ following parameters:
   ------------  -------------------------------------  ------------------------------  ---------------------------------------
   Type          Name                                   Default                         Description
   ------------  -------------------------------------  ------------------------------  ---------------------------------------
-  float[]       indexToObject                          1, 0, 0,                        An array of 12 values of type `float`
-                                                       0, 1, 0,                        that define the transformation from
-                                                       0, 0, 1,                        index space to object space.
-                                                       0, 0, 0                         In index space, the grid is an
-                                                                                       axis-aligned regular grid, and leaf
-                                                                                       voxels have size (1,1,1).
-                                                                                       The first 9 values are interpreted
-                                                                                       as a row-major linear transformation
-                                                                                       matrix. The last 3 values are the
+  affine3f      indexToObject                          1, 0, 0,                        Defines the transformation from index
+  float[]                                              0, 1, 0,                        space to object space. In index space,
+                                                       0, 0, 1,                        the grid is an axis-aligned regular
+                                                       0, 0, 0                         grid, and leaf voxels have size (1,1,1).
+                                                                                       A `vkl_affine3f` can be provided;
+                                                                                       alternatively an array of 12 values of
+                                                                                       type `float` can be used, where the
+                                                                                       first 9 values are interpreted as a
+                                                                                       row-major linear transformation matrix,
+                                                                                       and the last 3 values are the
                                                                                        translation of the grid origin.
 
   uint32[]      node.format                                                            For each input node, the data format.
@@ -898,6 +931,14 @@ following parameters:
   float[]       background                             `VKL_BACKGROUND_UNDEFINED`      For each attribute, the value that is
                                                                                        returned when sampling an undefined
                                                                                        region outside the volume domain.
+
+  box3i         indexClippingBounds                                                    Clips the volume to the specified
+                                                                                       index-space bounding box. This is
+                                                                                       useful for volumes with dimensions that
+                                                                                       are not even multiples of the leaf node
+                                                                                       dimensions, or .vdb files with
+                                                                                       restrictive active voxel bounding
+                                                                                       boxes.
   ------------  -------------------------------------  ------------------------------  ---------------------------------------
   : Configuration parameters for VDB (`"vdb"`) volumes.
 
@@ -1033,6 +1074,9 @@ radial basis function phi, for each particle that overlaps it. Gradients are
 similarly computed, based on the summed analytical contributions of each
 contributing particle.
 
+Particles with a radius less than or equal to zero are ignored. At least one
+valid particle (radius greater than zero) must be provided.
+
 The Open VKL implementation is similar to direct evaluation of samples in Reda
 et al.[2]. It uses an Embree-built BVH with a custom traversal, similar to the
 method in [1].

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -1,4 +1,4 @@
-## Copyright 2019-2020 Intel Corporation
+## Copyright 2019-2022 Intel Corporation
 ## SPDX-License-Identifier: Apache-2.0
 
 ## "Hello world" VKL tutorials ##
@@ -14,3 +14,7 @@ add_subdirectory(ispc)
 ## Interacive Examples ##
 
 add_subdirectory(interactive)
+
+## Minimal Console-based Examples ##
+
+add_subdirectory(minimal)
diff --git a/examples/interactive/ParameterGui.cpp b/examples/interactive/ParameterGui.cpp
@@ -1,4 +1,4 @@
-// Copyright 2021 Intel Corporation
+// Copyright 2021-2022 Intel Corporation
 // SPDX-License-Identifier: Apache-2.0
 
 #include "ParameterGui.h"
@@ -265,6 +265,8 @@ namespace openvkl {
 
         ImGui::PushID(id.c_str());
 
+        changed |= ImGui::SliderFloat(
+            "intervalResolutionHint", &p.intervalResolutionHint, 0.f, 1.f);
         changed |=
             ImGui::SliderFloat("Sampling rate", &p.samplingRate, 0.01f, 4.f);
 
@@ -310,6 +312,8 @@ namespace openvkl {
 
         ImGui::PushID(id.c_str());
 
+        changed |= ImGui::SliderFloat(
+            "intervalResolutionHint", &p.intervalResolutionHint, 0.f, 1.f);
         changed |=
             ImGui::SliderFloat("Color scale", &p.intervalColorScale, 1.f, 32.f);
         changed |=

diff --git a/examples/interactive/renderer/IntervalIteratorDebug.cpp b/examples/interactive/renderer/IntervalIteratorDebug.cpp
@@ -1,4 +1,4 @@
-// Copyright 2021 Intel Corporation
+// Copyright 2021-2022 Intel Corporation
 // SPDX-License-Identifier: Apache-2.0
 
 #include "IntervalIteratorDebug.h"
@@ -28,6 +28,10 @@ namespace openvkl {
       vklSetInt(
           intervalContext, "attributeIndex", rendererParams->attributeIndex);
 
+      vklSetFloat(intervalContext,
+                  "intervalResolutionHint",
+                  params->intervalResolutionHint);
+
       // set interval context value ranges based on transfer function positive
       // opacity intervals, if we have any
       VKLData valueRangesData = nullptr;

diff --git a/examples/interactive/renderer/IntervalIteratorDebug.h b/examples/interactive/renderer/IntervalIteratorDebug.h
@@ -1,4 +1,4 @@
-// Copyright 2021 Intel Corporation
+// Copyright 2021-2022 Intel Corporation
 // SPDX-License-Identifier: Apache-2.0
 
 #pragma once
@@ -10,6 +10,7 @@ namespace openvkl {
 
     struct IntervalIteratorDebugParams
     {
+      float intervalResolutionHint{0.5f};
       float intervalColorScale{4.f};
       float intervalOpacity{0.25f};
       bool firstIntervalOnly{false};

diff --git a/examples/interactive/renderer/RayMarchIteratorRenderer.cpp b/examples/interactive/renderer/RayMarchIteratorRenderer.cpp
@@ -1,4 +1,4 @@
-// Copyright 2021 Intel Corporation
+// Copyright 2021-2022 Intel Corporation
 // SPDX-License-Identifier: Apache-2.0
 
 #include "RayMarchIteratorRenderer.h"
@@ -30,6 +30,10 @@ namespace openvkl {
       vklSetInt(
           intervalContext, "attributeIndex", rendererParams->attributeIndex);
 
+      vklSetFloat(intervalContext,
+                  "intervalResolutionHint",
+                  params->intervalResolutionHint);
+
       // set interval context value ranges based on transfer function positive
       // opacity intervals, if we have any
       VKLData valueRangesData = nullptr;

diff --git a/examples/interactive/renderer/RayMarchIteratorRenderer.h b/examples/interactive/renderer/RayMarchIteratorRenderer.h
@@ -1,4 +1,4 @@
-// Copyright 2021 Intel Corporation
+// Copyright 2021-2022 Intel Corporation
 // SPDX-License-Identifier: Apache-2.0
 
 #pragma once
@@ -10,6 +10,7 @@ namespace openvkl {
 
     struct RayMarchIteratorRendererParams
     {
+      float intervalResolutionHint{0.5f};
       float samplingRate{1.f};
     };
 

diff --git a/examples/minimal/CMakeLists.txt b/examples/minimal/CMakeLists.txt
@@ -0,0 +1,9 @@
+## Copyright 2022 Intel Corporation
+## SPDX-License-Identifier: Apache-2.0
+
+# The minimal_01 ... minimal_06 examples gradually increase in complexity
+foreach(i 01 02 03 04 05 06)
+  add_executable(vklMinimal_${i} minimal_${i}.cpp ${VKL_RESOURCE})
+  target_link_libraries(vklMinimal_${i} PRIVATE openvkl)
+  install(TARGETS vklMinimal_${i} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+endforeach()
diff --git a/examples/minimal/README.md b/examples/minimal/README.md
@@ -0,0 +1,18 @@
+# Intel® Open Volume Kernel Library: Minimal Examples
+
+This directory contains a sequence of minimal code examples that make use of
+Open VKL. These examples are designed to be read and understood in sequence;
+each example builds upon the previous one.
+
+The examples provided are:
+
+- `minimal_01.cpp`: prerequisite code infrastructure for managing a framebuffer,
+  using a transfer function, and drawing the frame buffer to the terminal.
+- `minimal_02.cpp`: initializing Open VKL
+- `minimal_03.cpp`: instantiating a VKL volume, sampler, and rendering a slice
+- `minimal_04.cpp`: changing volume types
+- `minimal_05.cpp`: creating a ray marching volume renderer
+- `minimal_06.cpp`: creating an isosurface renderer
+
+For more complex examples, see the `vklExamples` application and corresponding
+code.
diff --git a/examples/minimal/create_voxels.h b/examples/minimal/create_voxels.h
@@ -0,0 +1,27 @@
+// Copyright 2021-2022 Intel Corporation
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "field.h"
+
+#include <vector>
+#include <cstddef>
+
+// The structured regular volume expects a data buffer that contains
+// all voxel values. We create it here by sampling the field() function, but
+// this data could be the output of a simulation, or loaded from disk.
+inline std::vector<float> createVoxels(size_t res)
+{
+  std::vector<float> voxels(res * res * res);
+  for (size_t z = 0; z < res; ++z)
+    for (size_t y = 0; y < res; ++y)
+      for (size_t x = 0; x < res; ++x) {
+        const float fx   = x / static_cast<float>(res);
+        const float fy   = y / static_cast<float>(res);
+        const float fz   = z / static_cast<float>(res);
+        const size_t idx = z * res * res + y * res + x;
+        voxels[idx]      = field(fx, fy, fz);
+      }
+  return voxels;
+}