Merge branch 'release-0.11.x'

Author: gregjohnson

CHANGELOG.md

@@ -1,6 +1,35 @@
 Version History
 ---------------
 
+### Open VKL 0.11.0
+
+-   Introduced API support for multi-attribute volumes, including APIs for
+    sampling multiple attributes simultaneously
+    -   Initially only `structuredRegular` and `structuredSpherical` volume
+        types support multi-attribute data
+-   Iterator APIs now work on sampler objects rather than volumes, supporting
+    finer-grained configurability
+-   Observers can now be created for both volume and sampler objects
+    -   `LeafNodeAccess` observers must now be created on sampler objects
+-   Log and error callbacks now support a user pointer
+-   `vdb` volume interval iterators:
+    -   Added support for elementary cell iteration when `maxIteratorDepth` is
+        set to `VKL_VDB_NUM_LEVELS`-1
+    -   Up to 2x faster iteration
+-   `unstructured` and `particle` volume interval iterators:
+    -   Improved interior empty space skipping behavior
+    -   Added support for configurable iterator depth via the `maxIteratorDepth`
+        parameter
+-   Added support for filter modes in `structuredRegular` and
+    `structuredSpherical` volumes
+-   `amr` volumes now support `method` parameter on sampler objects
+-   Added new `interval_iterator_debug` renderer in `vklExamples` to visualize
+    interval iteration behavior
+-   Hit iterator accuracy improvements for `unstructured` volumes
+-   Fixed bugs in `amr` and `vdb` volume bounding box computations
+-   Fixed bug in `unstructured` volume gradient computations near empty regions
+-   Minimum ISPC version is now v1.14.1
+
 ### Open VKL 0.10.0 (alpha)
 
 -   Added new `particle` volume type supporting Gaussian radial basis functions

CMakeLists.txt

@@ -19,7 +19,7 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
 ## Establish project ##
 
-project(openvkl VERSION 0.10.0 LANGUAGES C CXX)
+project(openvkl VERSION 0.11.0 LANGUAGES C CXX)
 
 ## Add openvkl specific macros ##
 

README.md

@@ -4,7 +4,7 @@
 option(OPENVKL_ISPC_FAST_MATH "enable ISPC fast-math optimizations" OFF)
 
 # ISPC versions to look for, in decending order (newest first)
-set(ISPC_VERSION_WORKING "1.10.0")
+set(ISPC_VERSION_WORKING "1.14.1")
 list(GET ISPC_VERSION_WORKING -1 ISPC_VERSION_REQUIRED)
 
 if (NOT ISPC_EXECUTABLE)

cmake/openvkl_ispc.cmake

@@ -249,6 +249,16 @@ function(openvkl_vdb_generate_topology)
       )
     endforeach()
 
+    configure_file(
+      ${PROJECT_SOURCE_DIR}/${PROJECT_NAME}/drivers/ispc/volume/vdb/VdbQueryVoxel.ih.in
+      include/${PROJECT_NAME}_vdb/VdbQueryVoxel_${VKL_VDB_LEVEL}.ih
+    )
+
+    configure_file(
+      ${PROJECT_SOURCE_DIR}/${PROJECT_NAME}/drivers/ispc/volume/vdb/HDDA.ih.in
+      include/${PROJECT_NAME}_vdb/HDDA_${VKL_VDB_LEVEL}.ih
+    )
+
   endforeach(I)
 
 endfunction()

cmake/openvkl_macros.cmake

@@ -21,7 +21,7 @@ you can build Open VKL you need the following prerequisites:
     have some version of OpenGL.
 
 -   Additionally you require a copy of the [Intel® SPMD Program Compiler
-    (ISPC)](http://ispc.github.io), version 1.12.0 or later. Please obtain a
+    (ISPC)](http://ispc.github.io), version 1.14.1 or later. Please obtain a
     release of ISPC from the [ISPC downloads
     page](https://ispc.github.io/downloads.html).
 

doc/api.md

@@ -20,7 +20,8 @@ For quick reference, the contents of `vklTutorial.c` are shown below.
 #include <stdio.h>
 
 #if defined(_MSC_VER)
-#include <malloc.h> // _malloca
+#include <malloc.h>   // _malloca
+#include <windows.h>  // Sleep
 #endif
 
 void demoScalarAPI(VKLVolume volume)
@@ -36,18 +37,36 @@ void demoScalarAPI(VKLVolume volume)
   printf("\t\tlower = %f %f %f\n", bbox.lower.x, bbox.lower.y, bbox.lower.z);
   printf("\t\tupper = %f %f %f\n\n", bbox.upper.x, bbox.upper.y, bbox.upper.z);
 
-  // value range
-  vkl_range1f valueRange = vklGetValueRange(volume);
-  printf("\tvalue range = (%f %f)\n\n", valueRange.lower, valueRange.upper);
+  // number of attributes
+  unsigned int numAttributes = vklGetNumAttributes(volume);
+  printf("\tnum attributes = %d\n\n", numAttributes);
 
-  // sample, gradient
-  vkl_vec3f coord = {1.f, 1.f, 1.f};
-  float sample    = vklComputeSample(sampler, &coord);
-  vkl_vec3f grad  = vklComputeGradient(sampler, &coord);
-  printf("\tcoord = %f %f %f\n", coord.x, coord.y, coord.z);
+  // value range (first attribute)
+  vkl_range1f valueRange = vklGetValueRange(volume);
+  printf("\tvalue range (first attribute) = (%f %f)\n\n",
+         valueRange.lower,
+         valueRange.upper);
+
+  // coordinate for sampling / gradients
+  vkl_vec3f coord = {1.f, 2.f, 3.f};
+  printf("\tcoord = %f %f %f\n\n", coord.x, coord.y, coord.z);
+
+  // sample, gradient (first attribute)
+  unsigned int attributeIndex = 0;
+  float sample   = vklComputeSample(sampler, &coord, attributeIndex);
+  vkl_vec3f grad = vklComputeGradient(sampler, &coord, attributeIndex);
+  printf("\tsampling and gradient computation (first attribute)\n");
   printf("\t\tsample = %f\n", sample);
   printf("\t\tgrad   = %f %f %f\n\n", grad.x, grad.y, grad.z);
 
+  // sample (multiple attributes)
+  unsigned int M                  = 3;
+  unsigned int attributeIndices[] = {0, 1, 2};
+  float samples[3];
+  vklComputeSampleM(sampler, &coord, samples, M, attributeIndices);
+  printf("\tsampling (multiple attributes)\n");
+  printf("\t\tsamples = %f %f %f\n\n", samples[0], samples[1], samples[2]);
+
   // value selector setup (note the commit at the end)
   vkl_range1f ranges[2]     = {{10, 20}, {50, 75}};
   int num_ranges            = 2;
@@ -75,12 +94,12 @@ void demoScalarAPI(VKLVolume volume)
 #if defined(_MSC_VER)
     // MSVC does not support variable length arrays, but provides a
     // safer version of alloca.
-    char *buffer = _malloca(vklGetIntervalIteratorSize(volume));
+    char *buffer = _malloca(vklGetIntervalIteratorSize(sampler));
 #else
-    char buffer[vklGetIntervalIteratorSize(volume)];
+    char buffer[vklGetIntervalIteratorSize(sampler)];
 #endif
     VKLIntervalIterator intervalIterator = vklInitIntervalIterator(
-        volume, &rayOrigin, &rayDirection, &rayTRange, selector, buffer);
+        sampler, &rayOrigin, &rayDirection, &rayTRange, selector, buffer);
 
     printf("\n\tinterval iterator for value ranges {%f %f} {%f %f}\n",
            ranges[0].lower,
@@ -109,12 +128,12 @@ void demoScalarAPI(VKLVolume volume)
 #if defined(_MSC_VER)
     // MSVC does not support variable length arrays, but provides a
     // safer version of alloca.
-    char *buffer = _malloca(vklGetHitIteratorSize(volume));
+    char *buffer = _malloca(vklGetHitIteratorSize(sampler));
 #else
-    char buffer[vklGetHitIteratorSize(volume)];
+    char buffer[vklGetHitIteratorSize(sampler)];
 #endif
     VKLHitIterator hitIterator = vklInitHitIterator(
-        volume, &rayOrigin, &rayDirection, &rayTRange, selector, buffer);
+        sampler, &rayOrigin, &rayDirection, &rayTRange, selector, buffer);
 
     printf("\thit iterator for values %f %f\n", values[0], values[1]);
 
@@ -141,26 +160,57 @@ void demoVectorAPI(VKLVolume volume)
   VKLSampler sampler = vklNewSampler(volume);
   vklCommit(sampler);
 
-  vkl_vvec3f4 coord4;  // structure-of-array layout
+  // structure-of-array layout
+  vkl_vvec3f4 coord4;
   int valid[4];
   for (int i = 0; i < 4; i++) {
-    coord4.x[i] = coord4.y[i] = coord4.z[i] = i;
-    valid[i] = -1;  // valid mask: 0 = not valid, -1 = valid
+    coord4.x[i] = i * 3 + 0;
+    coord4.y[i] = i * 3 + 1;
+    coord4.z[i] = i * 3 + 2;
+    valid[i]    = -1;  // valid mask: 0 = not valid, -1 = valid
   }
 
+  for (int i = 0; i < 4; i++) {
+    printf(
+        "\tcoord[%d] = %f %f %f\n", i, coord4.x[i], coord4.y[i], coord4.z[i]);
+  }
+
+  // sample, gradient (first attribute)
+  unsigned int attributeIndex = 0;
   float sample4[4];
   vkl_vvec3f4 grad4;
-  vklComputeSample4(valid, sampler, &coord4, sample4);
-  vklComputeGradient4(valid, sampler, &coord4, &grad4);
+  vklComputeSample4(valid, sampler, &coord4, sample4, attributeIndex);
+  vklComputeGradient4(valid, sampler, &coord4, &grad4, attributeIndex);
+
+  printf("\n\tsampling and gradient computation (first attribute)\n");
 
   for (int i = 0; i < 4; i++) {
-    printf(
-        "\tcoord[%d] = %f %f %f\n", i, coord4.x[i], coord4.y[i], coord4.z[i]);
     printf("\t\tsample[%d] = %f\n", i, sample4[i]);
     printf(
         "\t\tgrad[%d]   = %f %f %f\n", i, grad4.x[i], grad4.y[i], grad4.z[i]);
   }
 
+  // sample (multiple attributes)
+  unsigned int M                  = 3;
+  unsigned int attributeIndices[] = {0, 1, 2};
+  float samples[3 * 4];
+  vklComputeSampleM4(valid, sampler, &coord4, samples, M, attributeIndices);
+
+  printf("\n\tsampling (multiple attributes)\n");
+
+  printf("\t\tsamples = ");
+
+  for (unsigned int j = 0; j < M; j++) {
+    printf("%f %f %f %f\n",
+           samples[j * 4 + 0],
+           samples[j * 4 + 1],
+           samples[j * 4 + 2],
+           samples[j * 4 + 3]);
+    printf("\t\t          ");
+  }
+
+  printf("\n");
+
   vklRelease(sampler);
 }
 
@@ -175,20 +225,47 @@ void demoStreamAPI(VKLVolume volume)
   vkl_vec3f coord[5];
 
   for (int i = 0; i < 5; i++) {
-    coord[i].x = coord[i].y = coord[i].z = i;
+    coord[i].x = i * 3 + 0;
+    coord[i].y = i * 3 + 1;
+    coord[i].z = i * 3 + 2;
   }
 
+  for (int i = 0; i < 5; i++) {
+    printf("\tcoord[%d] = %f %f %f\n", i, coord[i].x, coord[i].y, coord[i].z);
+  }
+
+  // sample, gradient (first attribute)
+  printf("\n\tsampling and gradient computation (first attribute)\n");
+  unsigned int attributeIndex = 0;
   float sample[5];
   vkl_vec3f grad[5];
-  vklComputeSampleN(sampler, 5, coord, sample);
-  vklComputeGradientN(sampler, 5, coord, grad);
+  vklComputeSampleN(sampler, 5, coord, sample, attributeIndex);
+  vklComputeGradientN(sampler, 5, coord, grad, attributeIndex);
 
   for (int i = 0; i < 5; i++) {
-    printf("\tcoord[%d] = %f %f %f\n", i, coord[i].x, coord[i].y, coord[i].z);
     printf("\t\tsample[%d] = %f\n", i, sample[i]);
     printf("\t\tgrad[%d]   = %f %f %f\n", i, grad[i].x, grad[i].y, grad[i].z);
   }
 
+  // sample (multiple attributes)
+  unsigned int M                  = 3;
+  unsigned int attributeIndices[] = {0, 1, 2};
+  float samples[3 * 5];
+  vklComputeSampleMN(sampler, 5, coord, samples, M, attributeIndices);
+
+  printf("\n\tsampling (multiple attributes)\n");
+
+  printf("\t\tsamples = ");
+
+  for (int i = 0; i < 5; i++) {
+    for (unsigned int j = 0; j < M; j++) {
+      printf("%f ", samples[i * M + j]);
+    }
+    printf("\n\t\t          ");
+  }
+
+  printf("\n");
+
   vklRelease(sampler);
 }
 
@@ -200,10 +277,12 @@ int main()
   vklCommitDriver(driver);
   vklSetCurrentDriver(driver);
 
-  int dimensions[] = {128, 128, 128};
+  const int dimensions[] = {128, 128, 128};
 
   const int numVoxels = dimensions[0] * dimensions[1] * dimensions[2];
 
+  const int numAttributes = 3;
+
   VKLVolume volume = vklNewVolume("structuredRegular");
   vklSetVec3i(
       volume, "dimensions", dimensions[0], dimensions[1], dimensions[2]);
@@ -217,16 +296,44 @@ int main()
     return 1;
   }
 
-  // x-grad sample volume
+  // volume attribute 0: x-grad
   for (int k = 0; k < dimensions[2]; k++)
     for (int j = 0; j < dimensions[1]; j++)
       for (int i = 0; i < dimensions[0]; i++)
         voxels[k * dimensions[0] * dimensions[1] + j * dimensions[2] + i] =
             (float)i;
 
-  VKLData data = vklNewData(numVoxels, VKL_FLOAT, voxels, VKL_DATA_DEFAULT, 0);
-  vklSetData(volume, "data", data);
-  vklRelease(data);
+  VKLData data0 = vklNewData(numVoxels, VKL_FLOAT, voxels, VKL_DATA_DEFAULT, 0);
+
+  // volume attribute 1: y-grad
+  for (int k = 0; k < dimensions[2]; k++)
+    for (int j = 0; j < dimensions[1]; j++)
+      for (int i = 0; i < dimensions[0]; i++)
+        voxels[k * dimensions[0] * dimensions[1] + j * dimensions[2] + i] =
+            (float)j;
+
+  VKLData data1 = vklNewData(numVoxels, VKL_FLOAT, voxels, VKL_DATA_DEFAULT, 0);
+
+  // volume attribute 2: z-grad
+  for (int k = 0; k < dimensions[2]; k++)
+    for (int j = 0; j < dimensions[1]; j++)
+      for (int i = 0; i < dimensions[0]; i++)
+        voxels[k * dimensions[0] * dimensions[1] + j * dimensions[2] + i] =
+            (float)k;
+
+  VKLData data2 = vklNewData(numVoxels, VKL_FLOAT, voxels, VKL_DATA_DEFAULT, 0);
+
+  VKLData attributes[] = {data0, data1, data2};
+
+  VKLData attributesData =
+      vklNewData(numAttributes, VKL_DATA, attributes, VKL_DATA_DEFAULT, 0);
+
+  vklRelease(data0);
+  vklRelease(data1);
+  vklRelease(data2);
+
+  vklSetData(volume, "data", attributesData);
+  vklRelease(attributesData);
 
   vklCommit(volume);
 
@@ -240,6 +347,14 @@ int main()
 
   free(voxels);
 
+  printf("complete.\n");
+
+#if defined(_MSC_VER)
+  // On Windows, sleep for a few seconds so the terminal window doesn't close
+  // immediately.
+  Sleep(3000);
+#endif
+
   return 0;
 }
 ```

doc/compilation.md

@@ -16,13 +16,13 @@
 <div class="carousel-inner">
 
 <div class="carousel-item active">
-<img src="images/hacc.jpg">
+<img src="images/siggraph20_cloudscape.jpg">
 <div class="carousel-caption">
 <h3>
-Particle Volume Support
+SIGGRAPH 2020 demo: Interactive Volumetric Path Traced Cloudscape
 </h3>
 <p>
-Open VKL based volumetric path tracing of a 5.9 million particle subset of the HACC DarkSky simulation. Data courtesy of Salman Habib and Katrin Heitmann at Argonne National Laboratory.
+Interactive rendering of a large-scale volumetric cloudscape of VDB volumes, using Intel® Open Volume Kernel Library, Intel® OSPRay, and Intel® OSPRay Studio. <a href="https://www.youtube.com/watch?v=cpRMNuyiTig">Video</a>
 </p>
 </div>
 </div>
@@ -73,7 +73,7 @@ <h3>
 <div class="carousel-caption">
 <h3>Interactive Data Exploration</h3>
 <p>
-Loading leaf data from the Disney Moana cloud dataset while the user manipulates the viewport.
+Loading leaf data from the Disney Moana cloud dataset while the user manipulates the viewport. White regions indicate inner nodes, while blue regions indicate fully-loaded leaf data.
 </p>
 </div>
 </div>

doc/examples.md

@@ -26,6 +26,8 @@ openvkl_add_library_ispc(vkl_example_renderers STATIC
   renderers/DensityPathTracer.ispc
   renderers/HitIterator.cpp
   renderers/HitIterator.ispc
+  renderers/IntervalIteratorDebug.cpp
+  renderers/IntervalIteratorDebug.ispc
   renderers/RayMarchIterator.cpp
   renderers/RayMarchIterator.ispc
 )