SdrShaderNodeQuery is a constraint-based query builder object that operates on all SdrShaderNodes contained in the SdrRegistry. More...

#include <shaderNodeQuery.h>

Public Types
typedef std::function< bool(SdrShaderNodeConstPtr)>	FilterFn

Public Member Functions
SDR_API SdrShaderNodeQuery &	SelectDistinct (const TfToken &key)
	SelectDistinct asks for distinct information from SdrShaderNodes via the SdrShaderNode::GetDataForKey method.

SDR_API SdrShaderNodeQuery &	SelectDistinct (const std::vector< TfToken > &key)
	Specify multiple keys to query data for.

SDR_API SdrShaderNodeQuery &	CustomFilter (FilterFn fn)
	Supply a custom filter to this query.

SDR_API SdrShaderNodeQueryResult	Run ()
	Convenience to run this query on the SdrRegistry.

Node Filtering
NodeValueIs, NodeValueIsIn, NodeHasValueFor: These inclusion constraints are joined with each other by boolean "and" semantics, so only SdrShaderNodes that satisfy all of these inclusion constraints are kept. NodeValueIsNot, NodeValueIsNotIn, NodeHasNoValueFor: These exclusion constraints are joined with each other by boolean "or" semantics, so only SdrShaderNodes that satisfy none of these exclusion constraints are kept. Note nonexistence and empty VtValue are considered equivalent states. VtValue containing an empty item (e.g. empty string) is not equivalent to the former states. For example: node A has metadata {"foo": VtValue()} and node B has metadata {}. The metadata item keyed by "foo" does not exist on A; nor does it exist on B. As a consequence, NodeValueIs(key, VtValue()) is equivalent to NodeHasNoValueFor(key); and NodeHasValueFor(key) is equivalent to NodeValueIsNot(key, VtValue()). {@
SDR_API SdrShaderNodeQuery &	NodeValueIs (const TfToken &key, const VtValue &value)
	Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) matches the given `value`.

template<typename T >
SdrShaderNodeQuery &	NodeValueIs (const TfToken &key, const T &value)

SDR_API SdrShaderNodeQuery &	NodeValueIsIn (const TfToken &key, const std::vector< VtValue > &values)
	Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) matches any of the given `values`.

SDR_API SdrShaderNodeQuery &	NodeHasValueFor (const TfToken &key)
	Only keep SdrShaderNodes that have an existing value for for the given key.

SDR_API SdrShaderNodeQuery &	NodeValueIsNot (const TfToken &key, const VtValue &value)
	Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) doesn't match the given 'value'.

template<typename T >
SdrShaderNodeQuery &	NodeValueIsNot (const TfToken &key, const T &value)

SDR_API SdrShaderNodeQuery &	NodeValueIsNotIn (const TfToken &key, const std::vector< VtValue > &values)
	Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) doesn't match any of the given `values`.

SDR_API SdrShaderNodeQuery &	NodeHasNoValueFor (const TfToken &key)
	Only keep SdrShaderNodes that don't have an existing value for for the given key.

Friends
class	SdrRegistry

Detailed Description

SdrShaderNodeQuery is a constraint-based query builder object that operates on all SdrShaderNodes contained in the SdrRegistry.

Queries can be used to get nodes associated with given constraints, or to examine specific data from the nodes. For example, here's a query that indicates it wants all the nodes satisfying some constraints:

SdrShaderNodeQuery query = SdrShaderNodeQuery()
    .NodeValueIs(TfToken("customMetadataItem"), "stage2")
    .NodeValueIsNot(SdrNodeFieldKey->Identifier, "notthisone");

For this query, SdrRegistry::RunQuery(query) returns a result containing all the nodes associated with the given constraints.

Queries may additionally specify SelectDistinct to get aggregated data from the nodes satisfying given constraints. For example:

SdrShaderNodeQuery query2 = SdrShaderNodeQuery()
    .SelectDistinct(SdrNodeFieldKey->Family)
    .SelectDistinct(TfToken("customMetadataItem"))
    .NodeHasValueFor(TfToken("customMetadataItem"))

In this case, SdrRegistry::RunQuery(query2) would return a result containing distinct combinations of the requested family field and "customMetadataItem" values, along with the nodes satisfying said combinations under the given constraint that the node must have "customMetadataItem" defined in its metadata.

For more information on how query results are computed and represented, see SelectDistinct and SdrShaderNodeQueryResult.

See also: SdrShaderNodeQuery::SelectDistinct; SdrShaderNodeQueryResult

Note that SdrRegistry::RunQuery will cause all nodes in the registry to be parsed in order to examine data on these nodes in their final form.

Definition at line 62 of file shaderNodeQuery.h.

Member Typedef Documentation

◆ FilterFn

typedef std::function<bool (SdrShaderNodeConstPtr)> FilterFn

Definition at line 64 of file shaderNodeQuery.h.

Member Function Documentation

◆ CustomFilter()

SDR_API SdrShaderNodeQuery & CustomFilter ( FilterFn fn )

Supply a custom filter to this query.

This custom filter function will run on every considered SdrShaderNode. When this function evaluates to true, the node will be kept for further consideration. When the function evaluates to false, the node will be discarded from further consideration.

◆ NodeHasNoValueFor()

SDR_API SdrShaderNodeQuery & NodeHasNoValueFor ( const TfToken & key )

Only keep SdrShaderNodes that don't have an existing value for for the given key.

Empty values are considered "existing".

◆ NodeHasValueFor()

SDR_API SdrShaderNodeQuery & NodeHasValueFor ( const TfToken & key )

Only keep SdrShaderNodes that have an existing value for for the given key.

◆ NodeValueIs() [1/2]

SdrShaderNodeQuery & NodeValueIs	(	const TfToken &	key,
		const T &	value
	)

inline

Definition at line 135 of file shaderNodeQuery.h.

◆ NodeValueIs() [2/2]

SDR_API SdrShaderNodeQuery & NodeValueIs	(	const TfToken &	key,
		const VtValue &	value
	)

Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) matches the given value.

◆ NodeValueIsIn()

SDR_API SdrShaderNodeQuery & NodeValueIsIn	(	const TfToken &	key,
		const std::vector< VtValue > &	values
	)

Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) matches any of the given values.

◆ NodeValueIsNot() [1/2]

SdrShaderNodeQuery & NodeValueIsNot	(	const TfToken &	key,
		const T &	value
	)

inline

Definition at line 156 of file shaderNodeQuery.h.

◆ NodeValueIsNot() [2/2]

SDR_API SdrShaderNodeQuery & NodeValueIsNot	(	const TfToken &	key,
		const VtValue &	value
	)

Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) doesn't match the given 'value'.

◆ NodeValueIsNotIn()

SDR_API SdrShaderNodeQuery & NodeValueIsNotIn	(	const TfToken &	key,
		const std::vector< VtValue > &	values
	)

Only keep SdrShaderNodes whose value returned from SdrShaderNode::GetDataForKey(key) doesn't match any of the given values.

◆ Run()

SDR_API SdrShaderNodeQueryResult Run ( )

Convenience to run this query on the SdrRegistry.

Equivalent to SdrRegistry::RunQuery(query)

◆ SelectDistinct() [1/2]

SDR_API SdrShaderNodeQuery & SelectDistinct ( const std::vector< TfToken > & key )

Specify multiple keys to query data for.

See also: SelectDistinct(const TfToken& key)

◆ SelectDistinct() [2/2]

SDR_API SdrShaderNodeQuery & SelectDistinct ( const TfToken & key )

SelectDistinct asks for distinct information from SdrShaderNodes via the SdrShaderNode::GetDataForKey method.

Any number of keys can be requested via the SelectDistinct API on a single query. If SelectDistinct is not called and therefore no keys are requested, the result of running this query will contain no data but will contain nodes that satisfy the query filter constraints.

From each SdrShaderNode in the registry that satisfies the query filter constraints, this query will extract a "list of values" corresponding to the keys requested by SelectDistinct calls. SelectDistinct ensures that no duplicate "list of values" will appear in the SdrQueryResult. This echoes SQL's "SELECT DISTINCT" behavior. For example, these results are preserved as seen because they aren't duplicates of each other even though some entries are shared across them:

math, abs
math, add
brep, add

but the following duplicate results from different nodes would be coalesced into a single item instead.

math, abs
math, abs

If a data item requested by SelectDistinct doesn't exist for a node that otherwise satisfies all constraints of this query, an empty VtValue is used to represent the nonexistent item.

SdrShaderNodes from which these entries have been extracted will be returned alongside them in the query result.

See also: SdrShaderNodeQueryResult

Friends And Related Function Documentation

◆ SdrRegistry

friend class SdrRegistry

friend

Definition at line 189 of file shaderNodeQuery.h.

The documentation for this class was generated from the following file:

pxr/usd/sdr/shaderNodeQuery.h

Public Types

Public Member Functions

Friends