Developer preview release 2.3.6.1

OpenCue-launched apps are encouraged to honor the setting of
CUE_THREADS to limit the number of threads they use. This change makes
oiiotool (and other OIIO-based tools and scripts) better citizens when run
as part of an OpenCue job.

CUE_THREADS has lower precedence than the more OIIO-specific
`OPENIMAGEIO_THREADS`.

For ordinary command line usage, this should not change behavior, since
you wouldn't expect CUE_THREADS to be set.

(Also fix docs which incorrectly named `OPENIMAGEIO_TEXTURE_OPTIONS`.)

.github/workflows/ci.yml

@@ -116,8 +116,7 @@ jobs:
 
   vfxplatform-2021:
     # Test what's anticipated to be VFX Platform 2021 -- mainly, that means
-    # gcc9 and C++17. This test currently uses the latest OpenEXR release
-    # 2.5, though eventually 2021 will feature OpenEXR 3.0 when complete.
+    # gcc9 and C++17.
     name: "Linux VFX Platform 2021: gcc9/C++17 py3.7 boost-1.73 exr-2.5 qt-5.15"
     runs-on: ubuntu-latest
     container:
@@ -313,11 +312,11 @@ jobs:
       USE_SIMD: avx2,f16c
       LIBRAW_VERSION: 0.20.2
       LIBTIFF_VERSION: v4.3.0
-      OPENCOLORIO_VERSION: v2.0.0
-      OPENEXR_VERSION: v3.0.3
+      OPENCOLORIO_VERSION: v2.0.1
+      OPENEXR_VERSION: v3.1.0
       PUGIXML_VERSION: v1.11.4
       PTEX_VERSION: v2.4.0
-      PYBIND11_VERSION: v2.6.2
+      PYBIND11_VERSION: v2.7.0
       PYTHON_VERSION: 3.8
       WEBP_VERSION: v1.1.0
       MY_CMAKE_FLAGS: -DBUILD_FMT_VERSION=8.0.0
@@ -372,8 +371,7 @@ jobs:
       OPENEXR_VERSION: master
       PUGIXML_VERSION: master
       PTEX_VERSION: main
-      PYBIND11_VERSION: v2.6.2
-      # PYBIND11_VERSION: master
+      PYBIND11_VERSION: master
       PYTHON_VERSION: 3.8
       WEBP_VERSION: master
       MY_CMAKE_FLAGS: -DBUILD_FMT_VERSION=master -DOIIO_USE_EXR_C_API=ON

CHANGES.md

@@ -107,6 +107,12 @@ New major features and public API changes:
       libOpenImageIO depends on and links to libOpenImageIO_Util, rather
       than the utility classes being defined separately in both libraries.
       #2906 (2.3.4)
+* Environment variables:
+    - For users of OpenCue, the `CUE_THREADS` environment variable, if set,
+      is honored to limit the size of the thread pool that OIIO uses. Note
+      that `OPENIMAGEIO_THREADS` can override this, as can any direct setting
+      through the API or command line arguments of the utility programs.
+      #3038 (2.3.6.1)
 
 Performance improvements:
 * Speed up BMP reading by eliminating wasteful allocation and copying
@@ -328,6 +334,9 @@ Developer goodies / internals:
       (2.3.0.1/2.2.8)
     - `strhash()` is now constexpr for C++14 and higher. #2843 (2.3.3)
     - Strutil new functions: find, rfind, ifind, irfind (#2960) (2.3.4/2.2.14)
+* sysutil.h:
+    - getenv() extended to take a default value to return if the environment
+      variable is not found. #3037 #3040 (2.3.6.1)
 * typedesc.h:
     - `TypeDesc::basetype_merge(a,b)` returns a BASETYPE having the
       precision and range to hold the basetypes of either `a` or `b`.

CMakeLists.txt

@@ -3,7 +3,7 @@
 # https://github.com/OpenImageIO/oiio/blob/master/LICENSE.md
 
 cmake_minimum_required (VERSION 3.12)
-project (OpenImageIO VERSION 2.3.6.0
+project (OpenImageIO VERSION 2.3.6.1
          HOMEPAGE_URL "https://openimageio.org"
          LANGUAGES CXX C)
 set (PROJ_NAME OIIO)    # short name, caps

INSTALL.md

@@ -19,7 +19,7 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
        CMake configuration flag: `-DCMAKE_CXX_STANDARD=17`, etc.
  * Compilers: **gcc 6.1 - 11.1**, **clang 3.4 - 12**, **MSVS 2017 - 2019**,
    **icc 17+**.
- * CMake >= 3.12 (tested through 3.20)
+ * CMake >= 3.12 (tested through 3.21)
  * OpenEXR/Imath >= 2.0 (recommended: 2.2 or higher; tested through 3.1)
  * libTIFF >= 3.9 (recommended: 4.0+; tested through 4.3)
  * Boost >= 1.53 (recommended: at least 1.66; tested through 1.76)
@@ -31,7 +31,7 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
      * OpenGL
  * If you are building the Python bindings or running the testsuite:
      * Python >= 2.7 (tested against 2.7, 3.6, 3.7, 3.8, 3.9)
-     * pybind11 >= 2.4.2 (Tested through 2.6.)
+     * pybind11 >= 2.4.2 (Tested through 2.7.)
      * NumPy
  * If you want support for camera "RAW" formats:
      * LibRaw >= 0.15 (tested 0.15 - 0.20; LibRaw >= 0.18 is necessary for

src/doc/imageioapi.rst

@@ -316,7 +316,7 @@ inside the source code.
         imagecache->attribute ("options", value);
 
 
-``OPENIMAGEIO_TEXTURESYSTEM_OPTIONS``
+``OPENIMAGEIO_TEXTURE_OPTIONS``
 
     Allows you to seed the options for any TextureSystem created.
 
@@ -328,3 +328,10 @@ inside the source code.
     will be passed to a call to::
 
         texturesys->attribute ("options", value);
+
+``OPENIMAGEIO_THREADS``, ``CUE_THREADS``
+
+    Either of these sets the default number of threads that OpenImageIO will
+    use for its thread pool. If both are set, ``OPENIMAGEIO_THREADS`` will
+    take precedence. If neither is set, the default will be 0, which means
+    to use as many threads as there are physical cores on the machine.

src/include/OpenImageIO/sysutil.h

@@ -63,8 +63,13 @@ get_local_time(const time_t* time, struct tm* converted_time);
 OIIO_API std::string
 this_program_path();
 
-/// Return the value of an environment variable (or the empty string_view
-/// if it is not found in the environment.)
+/// Return the value of an environment variable, or if it is not found in
+/// the environment, return `defaultval`, which in turn defaults to the
+/// empty string.
+OIIO_API string_view
+getenv(string_view name, string_view defaultval);
+
+// Legacy for link compatibility. DEPRECATED(2.3)
 OIIO_API string_view
 getenv(string_view name);
 

src/libOpenImageIO/imageio.cpp

@@ -24,7 +24,8 @@ OIIO_NAMESPACE_BEGIN
 static int
 threads_default()
 {
-    int n = Strutil::from_string<int>(Sysutil::getenv("OPENIMAGEIO_THREADS"));
+    int n = Strutil::from_string<int>(
+        Sysutil::getenv("OPENIMAGEIO_THREADS", Sysutil::getenv("CUE_THREADS")));
     if (n < 1)
         n = Sysutil::hardware_concurrency();
     return n;

src/libutil/sysutil.cpp

@@ -61,6 +61,7 @@
 #include <OpenImageIO/dassert.h>
 #include <OpenImageIO/strutil.h>
 #include <OpenImageIO/sysutil.h>
+#include <OpenImageIO/ustring.h>
 
 #include <boost/version.hpp>
 #if BOOST_VERSION >= 106500
@@ -270,10 +271,22 @@ Sysutil::this_program_path()
 
 
 
+string_view
+Sysutil::getenv(string_view name, string_view defaultval)
+{
+    const char* env = ::getenv(std::string(name).c_str());
+    if (!env && defaultval.size())
+        env = ustring(defaultval).c_str();
+    return string_view(env ? env : "");
+}
+
+
+
 string_view
 Sysutil::getenv(string_view name)
 {
-    return string_view(::getenv(name.c_str()));
+    const char* env = ::getenv(std::string(name).c_str());
+    return string_view(env ? env : "");
 }
 
 

src/libutil/thread.cpp

@@ -88,7 +88,8 @@ OIIO_NAMESPACE_BEGIN
 static int
 threads_default()
 {
-    int n = Strutil::from_string<int>(Sysutil::getenv("OPENIMAGEIO_THREADS"));
+    int n = Strutil::from_string<int>(
+        Sysutil::getenv("OPENIMAGEIO_THREADS", Sysutil::getenv("CUE_THREADS")));
     if (n < 1)
         n = Sysutil::hardware_concurrency();
     return n;