From 4891861da3088476a72b54f835ad6ed43aea4ace Mon Sep 17 00:00:00 2001 From: Larry Gritz Date: Sun, 28 Dec 2025 00:06:33 -0800 Subject: [PATCH] docs: fix missing docs for `OIIO:attribute()` and `OIIO::getattribute()` Rearrangements in 3.1 dropped the list of recognized attributes and failed to document the span varieties. We fix and also reword a lot of the descriptions for clarity and uniformity. Signed-off-by: Larry Gritz --- src/doc/imageioapi.rst | 45 +------ src/include/OpenImageIO/imageio.h | 188 +++++++++++++++++++++--------- 2 files changed, 135 insertions(+), 98 deletions(-) diff --git a/src/doc/imageioapi.rst b/src/doc/imageioapi.rst index d2d6b192b4..bf1c22dd07 100644 --- a/src/doc/imageioapi.rst +++ b/src/doc/imageioapi.rst @@ -215,49 +215,12 @@ These helper functions are not part of any other OpenImageIO class, they just exist in the OpenImageIO namespace as general utilities. (See :ref:`sec-pythonmiscapi` for the corresponding Python bindings.) -.. doxygenfunction:: OIIO::attribute(string_view, TypeDesc, const void *) - -.. cpp:function:: bool OIIO::attribute(string_view name, int val) - bool OIIO::attribute(string_view name, float val) - bool OIIO::attribute(string_view name, string_view val) - - Shortcuts for setting an attribute to a single int, float, or string. - - -.. doxygenfunction:: OIIO::getattribute(string_view, TypeDesc, void *) - - -.. cpp:function:: bool getattribute (string_view name, int &val) - bool getattribute (string_view name, float &val) - bool getattribute (string_view name, char **val) - bool getattribute (string_view name, std::string& val) - - Specialized versions of `getattribute()` in which the data type is - implied by the type of the argument (for single int, float, or string). - Two string versions exist: one that retrieves it as a `std::string` and - another that retrieves it as a `char *`. In all cases, the return value - is `true` if the attribute is found and the requested data type - conversion was legal. - - EXAMPLES:: - - int threads; - OIIO::getattribute ("threads", &threads); - std::string path; - OIIO::getattribute ("plugin_searchpath", path); - -.. cpp:function:: int get_int_attribute (string_view name, int defaultvalue=0) - float get_float_attribute (string_view name, float defaultvalue=0) - string_view get_string_attribute (string_view name, string_view defaultvalue="") - - Specialized versions of `getattribute()` for common types, in which the - data is returned directly, and a supplied default value is returned if - the attribute was not found. +.. doxygengroup:: OIIO_attribute +.. - EXAMPLES:: - int threads = OIIO::get_int_attribute ("threads", 0); - string_view path = OIIO::get_string_attribute ("plugin_searchpath"); +.. doxygengroup:: OIIO_getattribute +.. diff --git a/src/include/OpenImageIO/imageio.h b/src/include/OpenImageIO/imageio.h index e6c1ab0552..4b9a05304b 100644 --- a/src/include/OpenImageIO/imageio.h +++ b/src/include/OpenImageIO/imageio.h @@ -3697,18 +3697,28 @@ OIIO_API bool has_error(); /// error messages. OIIO_API std::string geterror(bool clear = true); -/// `OIIO::attribute()` sets a global attribute (i.e., a property or -/// option) of OpenImageIO. The `name` designates the name of the attribute, -/// `type` describes the type of data, and `value` is a pointer to memory -/// containing the new value for the attribute. +/// @defgroup OIIO_attribute (global OIIO::attribute()) +/// @{ /// -/// If the name is known, valid attribute that matches the type specified, -/// the attribute will be set to the new value and `attribute()` will return -/// `true`. If `name` is not recognized, or if the types do not match -/// (e.g., `type` is `TypeFloat` but the named attribute is a string), the -/// attribute will not be modified, and `attribute()` will return `false`. +/// `OIIO::attribute()` sets a global attribute (i.e., a property or option) +/// of OpenImageIO. The `name` designates the name of the attribute, `value` +/// is the value to use for the attribute, and for some varieties of the call, +/// `type` is a TypeDesc describing the data type. /// -/// The following are the recognized attributes: +/// Most varieties of the call will return `true` if `name` is a known +/// attribute and its expected type is compatible with the type specified. If +/// `name` is not recognized, or if the types do not match (e.g., `type` is +/// `TypeFloat` but the named attribute is supposed to be a string), the +/// internal attribute will not be modified, and `attribute()` will return +/// `false`. +/// +/// In all cases, is up to the caller to ensure that `value` is or refers to +/// the right kind and size of storage for the given type. +/// +/// Note that all attributes set by this call may also be retrieved by +/// `OIIO::getattribute()`. +/// +/// RECOGNIZED ATTRIBUTES /// /// - `string options` /// @@ -3927,7 +3937,25 @@ OIIO_API std::string geterror(bool clear = true); /// enable globally in an environment where security is a higher priority /// than being tolerant of partially broken image files. /// -/// @version 3.1 +/// EXAMPLES: +/// ``` +/// // Setting single simple values simply: +/// bool ok = OIIO::getattribute("threads", 1); // implied: int +/// ok = OIIO::attribute("plugin_searchpath", "/foo/bar:/baz"); // implied: string +/// +/// // Setting a more complex value using a span, with explicit type +/// float missing[4] = { 0.0f, 0.0f, 0.0f, 1.0f }; +/// ok = OIIO::attribute("missingcolor", TypeDesc("float[4]"), make_span(missing)); +/// ``` +/// +/// The different varieties of `OIIO::attribute()` call follow: + +/// Set the attribute's value from a span (which may be a single value). The +/// total size of `value` must match the `type` (if not, an assertion will be +/// thrown for debug builds of OIIO, an error will be printed for release +/// builds). +/// +/// @version 3.1+ template inline bool attribute(string_view name, TypeDesc type, span value) { @@ -3936,19 +3964,18 @@ inline bool attribute(string_view name, TypeDesc type, span value) return attribute(name, type, OIIO::as_bytes(value)); } -/// A version of `OIIO::attribute()` that takes its value from a span of -/// untyped bytes. The total size of `value` must match the `type` (if not, an -/// assertion will be thrown for debug builds of OIIO, an error will be -/// printed for release builds). +/// Set the attribute's value from a span of untyped bytes. The total size of +/// `value` must match the `type` (if not, an assertion will be thrown for +/// debug builds of OIIO, an error will be printed for release builds). /// -/// @version 3.1 +/// @version 3.1+ OIIO_API bool attribute(string_view name, TypeDesc type, cspan value); -/// A version of `OIIO::attribute()` where the `value` is only a pointer -/// specifying the beginning of the memory where the value should be copied -/// from. This is "unsafe" in the sense that there is no assurance that it -/// points to a sufficient amount of memory, so the span-based versions of -/// `attribute()` are preferred. +/// Set the named attribute to the contents of memory pointed to by `value`, +/// with the `type` implying the total size to be copied. This is "unsafe" in +/// the sense that there is no assurance that it points to a sufficient amount +/// of memory or value type, so the span-based versions of `attribute()` are +/// preferred. /// /// This was added in version 2.1. OIIO_API bool attribute(string_view name, TypeDesc type, const void* value); @@ -3967,12 +3994,23 @@ inline bool attribute(string_view name, string_view value) { const char *s = valstr.c_str(); return attribute(name, TypeString, &s); } +/// @} + -/// Get the named global attribute of OpenImageIO, store it in `value`. -/// Return `true` if found and it was compatible with the type specified, -/// otherwise return `false` and do not modify the contents of `value`. It -/// is up to the caller to ensure that `val` points to the right kind and -/// size of storage for the given type. +/// @defgroup OIIO_getattribute (global OIIO::getattribute()) +/// @{ +/// +/// `OIIO::getattribute()` retrieves a named global attribute of OpenImageIO, +/// and stores it in `value`. These are the retrieval side of the symmetric +/// set of `OIIO::attribute()` calls. +/// +/// Most varieties of the call will return `true` if the named attribute was +/// found and it was compatible with the type specified, otherwise return +/// `false` and do not modify the contents of `value`. In all cases, it is up +/// to the caller to ensure that `val` points to the right kind and size of +/// storage for the given type. +/// +/// RECOGNIZED ATTRIBUTES /// /// In addition to being able to retrieve all the attributes that are /// documented as settable by the `OIIO::attribute()` call, `getattribute()` @@ -4104,8 +4142,32 @@ inline bool attribute(string_view name, string_view value) { /// IBA::resize 20 0.24s (avg 12.18ms) /// IBA::zero 8 0.66ms (avg 0.08ms) /// +/// EXAMPLES: +/// ``` +/// // Retrieving a single simple value with success/failure return: +/// int threads; +/// bool ok = OIIO::getattribute("threads", threads); +/// std::string path; +/// ok = OIIO::getattribute("plugin_searchpath", path); /// -/// @version 3.1 +/// // Directly returning a single simple value, with default to use +/// // if the attribute is not found: +/// int threads = OIIO::get_int_attribute("threads", 0); +/// string_view path = OIIO::get_string_attribute("plugin_searchpath"); +/// +/// // Returning into a span, with explicit type +/// float missing[4]; +/// ok = OIIO::getattribute("missingcolor", TypeDesc("float[4]"), +/// make_span(missing)); +/// ``` +/// +/// The different varieties of `OIIO::getattribute()` call follow: + +/// Store the named attribute's current value into a writable span. The total +/// size of `value` must match the `type` (if not, an assertion will be thrown +/// for debug OIIO builds, an error will be printed for release builds). +/// +/// @version 3.1+ template inline bool getattribute(string_view name, TypeDesc type, span value) { @@ -4114,37 +4176,37 @@ inline bool getattribute(string_view name, TypeDesc type, span value) return OIIO::v3_1::getattribute(name, type, OIIO::as_writable_bytes(value)); } -/// A version of `getattribute()` that stores the value in a span of -/// untyped bytes. The total size of `value` must match the `type` (if -/// not, an assertion will be thrown for debug OIIO builds, an error will -/// be printed for release builds). +/// Store the value in a span of untyped bytes. The total size of `value` must +/// match the `type` (if not, an assertion will be thrown for debug OIIO +/// builds, an error will be printed for release builds). /// -/// @version 3.1 +/// @version 3.1+ OIIO_API bool getattribute(string_view name, TypeDesc type, span value); -/// A version of `OIIO::getattribute()` where the `value` is only a pointer -/// specifying the beginning of the memory where the value should be copied. -/// This is "unsafe" in the sense that there is no assurance that it points to -/// a sufficient amount of memory, so the span-based versions of `attribute()` -/// are preferred. +/// Store the value into memory pointed to by `val`. This is "unsafe" in the +/// sense that there is no assurance that it points to a sufficient amount of +/// memory or will be interpreted as the correct type, so the span-based +/// versions of `attribute()` are preferred. OIIO_API bool getattribute(string_view name, TypeDesc type, void* val); -/// Shortcut getattribute() for retrieving a single integer. The value is -/// placed in `value`, and the function returns `true` if the attribute was -/// found and was legally convertible to an int. +/// Retrieve a single-integer attribute. The value is placed in `value`, and +/// the function returns `true` if the attribute was found and was legally +/// convertible to an int. inline bool getattribute (string_view name, int &value) { return getattribute (name, TypeInt, &value); } -/// Shortcut getattribute() for retrieving a single float. The value is placed -/// in `value`, and the function returns `true` if the attribute was found and -/// was legally convertible to a float. + +/// Retrieve a single-float attribute. The value is placed in `value`, and the +/// function returns `true` if the attribute was found and was legally +/// convertible to a float. inline bool getattribute (string_view name, float &value) { return getattribute (name, TypeFloat, &value); } -/// Shortcut getattribute() for retrieving a single string as a `std::string`. -/// The value is placed in `value`, and the function returns `true` if the -/// attribute was found. + +/// Retrieve a single-string attribute, placed as a `std::string` into +/// `value`, and the function returns `true` if the attribute was found and +/// was legally convertible to an string. inline bool getattribute (string_view name, std::string &value) { ustring s; bool ok = getattribute (name, TypeString, &s); @@ -4152,32 +4214,44 @@ inline bool getattribute (string_view name, std::string &value) { value = s.string(); return ok; } -/// Shortcut getattribute() for retrieving a single string as a `char*`. -inline bool getattribute (string_view name, char **val) { - return getattribute (name, TypeString, val); + +/// Retrieve a single-string attribute, placed as a `const char*` into +/// `*value`, and the function returns `true` if the attribute was found and +/// was legally convertible to an string. Note that the `const char*` +/// retrieved is really the characters belonging to a `ustring`, and so is +/// owned by OIIO and should not be freed by the calling code. +inline bool getattribute (string_view name, char **value) { + return getattribute (name, TypeString, value); } -/// Shortcut getattribute() for retrieving a single integer, with a supplied -/// default value that will be returned if the attribute is not found or -/// could not legally be converted to an int. + +/// Retrieve a single-integer attribute, with a supplied default value that +/// will be returned if the attribute is not found or could not legally be +/// converted to an int. inline int get_int_attribute (string_view name, int defaultval=0) { int val; return getattribute (name, TypeInt, &val) ? val : defaultval; } -/// Shortcut getattribute() for retrieving a single float, with a supplied -/// default value that will be returned if the attribute is not found or -/// could not legally be converted to a float. + +/// Retrieve a single-float attribute, with a supplied default value that +/// will be returned if the attribute is not found or could not legally be +/// converted to a float. inline float get_float_attribute (string_view name, float defaultval=0) { float val; return getattribute (name, TypeFloat, &val) ? val : defaultval; } -/// Shortcut getattribute() for retrieving a single string, with a supplied -/// default value that will be returned if the attribute is not found. + +/// Retrieve a single-string attribute, with a supplied default value that +/// will be returned if the attribute is not found or could not legally be +/// converted to an int. default value that will be returned if the attribute +/// is not found. inline string_view get_string_attribute (string_view name, string_view defaultval = string_view()) { ustring val; return getattribute (name, TypeString, &val) ? string_view(val) : defaultval; } +/// @} + /// Set the metadata of the `spec` to presume that color space is `name` (or /// to assume nothing about the color space if `name` is empty). The core