**OSLQuery Documentation** Introduction and Tutorial ========================= `OSLQuery` is a class that lets an application interrogate a compiled shader for information about its parameters. The shader may be an already-compiled shader file on disk (i.e. a `.oso` file), or the `.oso` equivalent in a string, or the binary representation used by the OSL `ShaderSystem` runtime (as a pointer to a `ShaderGroup`). For example, ~~~ OSLQuery oslquery ("polished_oak"); ~~~ It's then easy to retrieve a specific parameter: ~~~ int nparams = oslquery.nparams(); // number of params const OSLQuery::Parameter *param; p = oslquery.getparam (i); // by index (0..nparams-1) p = oslquery.getparam ("woodcolor"); // by name ~~~ And the `Parameter` structure will hold all the information you need about that parameter. For example: ~~~ std::cout << "Parameter " << p->name << " is type " << p->type << "\n" ~~~ You can find out if the parameter is a closure, an output parameter, etc. You can also find out its default values, which are stored in vector fields `idefault`, `fdefault`, and `sdefault` depending on whether the types is based on int, float, or string, respectively. OSLQuery class API Reference ============================ Parameter helper structure -------------------------- `Parameter` holds all the information about a single shader parameter. OSLQuery methods ---------------- ~~~C OSLQuery() ~~~ Construct an uninitialized OSLQuery. It will not hold any information about a shader until `open()` is called. ~~~C OSLQuery(string_view shadername, string_view searchpath = string_view()) ~~~ Construct an OSLQuery and open a compiled shader from a disk file. The `shadername` may be either the name of the `.oso` file, or the name of the shader. The optional `searchpath` parameter gives a colon-separated list of directories to search for compiled shaders. ~~~C OSL_DEPRECATED("Use ShadingSystem::oslquery(group,layernum)") OSLQuery(const ShaderGroup* group, int layernum) // DEPRECATED(1.12) ~~~ Construct an OSLQuery and initialize it with an existing `ShaderGroup` (which must have been built using the `ShadingSystem` runtime API for OSL). This constructor only exists in liboslexec, with a full shading system, and not in liboslquery. This is deprecated, and instead we recommend retrieving an OSLQuery via `ShadingSystem::oslquery(group, layernum)`. ~~~C ~OSLQuery() ~~~ Clean up and destruct the `OSLQuery`. ~~~C bool open(string_view shadername, string_view searchpath = string_view()) ~~~ For an uninitialized `OSLQuery` object, initialize it with info on the named shader with optional searchpath. Return true for success, false if the shader could not be found or opened properly. ~~~C bool open_bytecode(string_view buffer) ~~~ Get info on the shader from it's compiled bytecode (i.e., like the contents of an `.oso` file, but in a string). Return `true` for success, false if the shader could not be found or opened properly. This is meant to be called from an app which caches bytecodes from it's own side and wants to get shader info on runtime without creating a temporary file. ~~~C bool init(const ShaderGroup* group, int layernum) // DEPRECATED(1.12) ~~~ Meant to be called at runtime from an app with a full ShadingSystem, fill out an OSLQuery structure for the given layer of the group. This is much faster than using open() to read it from an oso file on disk. This is deprecated, and instead we recommend retrieving an OSLQuery via `ShadingSystem::oslquery(group, layernum)`. ~~~C const ustring shadertype(void) const ~~~ Return the shader type: "surface", "displacement", "volume", "light", or "shader" (for generic shaders). ~~~C const ustring shadername(void) const ~~~ Get the name of the shader. ~~~C size_t nparams(void) const ~~~ How many parameters does the shader have ~~~C const Parameter* getparam(size_t i) const const Parameter* getparam(const std::string& name) const const Parameter* getparam(ustring name) const ~~~ Retrieve a parameter, either by index or by name. Return nullptr if the index is out of range, or if the named parameter is not found. ~~~C const std::vector& parameters(void) const ~~~ Retrieve a reference to the list of the shader's parameters. ~~~C const std::vector& metadata(void) const ~~~ Retrieve a reference to the metadata about the shader. ~~~C std::string geterror(bool clear_error = true) ~~~ Return error string, empty if there was no error, and reset the error string. Example program using OSLQuery ============================== This is the full text of `oslinfo`, a command-line utility that for any shader, will print out its parameters (name, type, default values, and metadata). ~~~~ ~~~~