api: consistent naming of OPENIMAGEIO_PLUGIN_PATH env variable (#4330)

The old name, OIIO_LIBRARY_PATH, was inconsistently named in two ways:

First, it was not clear that it was specific to searching for plugins,
and since it is related to the to the global attribute
"plugin_searchpath", I thought making it mention plugins specifically
would be more clear.

Second, I noticed that all of the publicly documented environment
variables that are "for users" started with OPENIMAGEIO_, except for
this one. There are a bunch of environment variables we check that begin
with OIIO_, but all but this one are intended for developers when
testing or debugging.

So I'm using a new name that is consistent with both principles.

Henceforth, the naming rule about environment variables is:

* `OPENIMAGEIO_FOO` for public interfaces, are fully documented and
intended for users/sites to use to customize behavior.

* `OIIO_FOO` for developers to use when testing and debugging, are
undocumented (except in the code itself), and are not considered part of
the public API/behavior of OpenImageIO -- their meaning may change, they
may disappear without warning, or they may only be functional for debug
builds.

Signed-off-by: Larry Gritz <[email protected]>

src/doc/imageioapi.rst

@@ -340,6 +340,16 @@ inside the source code.
         imagecache->attribute ("options", value);
 
 
+``OPENIMAGEIO_PLUGIN_PATH``
+
+    A colon-separated list of directories to search for OpenImageIO plugins
+    (dynamicaly loadable libraries that implement image format readers
+    and writers).
+
+    This is a new name beginning with OpenImageIO 2.6.3. The old name
+    ``OIIO_LIBRARY_PATH`` is still supported, but deprecated.
+
+
 ``OPENIMAGEIO_TEXTURE_OPTIONS``
 
     Allows you to seed the options for any TextureSystem created.

src/doc/imageoutput.rst

@@ -1647,7 +1647,7 @@ user's home directory is :file:`/home/tom`), and if not found there, will
 then check the directory :file:`/shared/plugins`.
 
 The first search path it will check is that stored in the environment
-variable ``OIIO_LIBRARY_PATH``.  It will check each directory in turn, in
+variable ``OPENIMAGEIO_PLUGIN_PATH``.  It will check each directory in turn, in
 the order that they are listed in the variable.  If no adequate plugin is
 found in any of the directories listed in this environment variable, then it
 will check the custom searchpath passed as the optional second argument to

src/libOpenImageIO/imageioplugin.cpp

@@ -468,6 +468,8 @@ pvt::catalog_all_plugins(std::string searchpath)
     std::call_once(builtin_flag, catalog_builtin_plugins);
 
     std::unique_lock<std::recursive_mutex> lock(imageio_mutex);
+    append_if_env_exists(searchpath, "OPENIMAGEIO_PLUGIN_PATH", true);
+    // obsolete name:
     append_if_env_exists(searchpath, "OIIO_LIBRARY_PATH", true);
 
     size_t patlen = pattern.length();