Skip to content

Commit

Permalink
Update hd with new MaterialOverrideSchema and add docs to relevant sc…
Browse files Browse the repository at this point in the history 
…hemas.

The schema is designed to live on a 'material' prim type as a data source of the following structure:
materialOverride.interfaceValues.<publicUIName>.value -> value

Note that 'materialOverride' is a container data source with one member 'interfaceValues'.
Each interfaceValue specifies the overriding data source, which follows the MaterialNodeParameter schema.

(Internal change: 2336028)
  • Loading branch information
@vverovvero @pixar-oss
vverovvero authored and pixar-oss committed Aug 6, 2024
1 parent 6eb78e2 commit 30392d9
Show file tree
Hide file tree
Showing 10 changed files with 595 additions and 6 deletions.
1 change: 1 addition & 0 deletions pxr/imaging/hd/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ pxr_library(hd
materialNetwork2Interface
materialNodeSchema
materialNodeParameterSchema
materialOverrideSchema
materialSchema
mergingSceneIndex
mesh
Expand Down
178 changes: 172 additions & 6 deletions pxr/imaging/hd/hdSchemaDefs.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -371,10 +371,38 @@
# materialNode
dict(
SCHEMA_NAME = 'MaterialNode',
DOC = '''
The MaterialNode schema is a container schema that defines a
particular node in a material network.
A material node defines its connections to other nodes via the
"inputConnections" member. For example, "albedo" would define that
it receives its value from its connection to the node
"Color_UnPreMult" and the output "resultRGB" with the following data
sources:
ds at: material/<renderContext>/nodes/MaterialLayer/inputConnections
/albedo/[0]/upstreamNodePath = Color_UnPreMult
ds at: material/<renderContext>/nodes/MaterialLayer/inputConnections
/albedo/[0]/upstreamNodeOutputName = resultRGB
''',
SCHEMA_INCLUDES = ['{{LIBRARY_PATH}}/schemaTypeDefs'],
MEMBERS = [
('parameters', 'HdMaterialNodeParameterContainerSchema', {}),
('inputConnections', 'HdMaterialConnectionVectorContainerSchema', {}),
('parameters', 'HdMaterialNodeParameterContainerSchema',
dict(DOC = '''
Maps parameter names to node parameters. Each node parameter
is a container that is defined by the MaterialNodeParameter
schema. Note that parameters are inputs that supply their value
directly.
''')),
('inputConnections', 'HdMaterialConnectionVectorContainerSchema',
dict(DOC = '''
Maps input names to vectors of connections. Each connection is
defined by the MaterialConnection schema. Note that
inputConnections are inputs that get their value from data flow
over the connection.
''')),
('nodeIdentifier', T_TOKEN,
dict(DOC = '''
This identifies the shader the node represents. The
Expand Down Expand Up @@ -405,6 +433,10 @@
# materialNodeParameter
dict(
SCHEMA_NAME = 'MaterialNodeParameter',
DOC = '''
The MaterialNodeParameter schema defines the value data source for
the parameter.
''',
MEMBERS = [
('value', T_SAMPLED, {}),
# Parameter Metadata
Expand All @@ -416,6 +448,13 @@
# materialConnection
dict(
SCHEMA_NAME = 'MaterialConnection',
DOC = '''
The MaterialConnection schema defines an upstream connected node and
output.
See MaterialNode schema's documentation on its
'inputConnections' member for an example.
''',
MEMBERS = [
('upstreamNodePath', T_TOKEN, {}),
('upstreamNodeOutputName', T_TOKEN, {}),
Expand All @@ -426,6 +465,13 @@
# materialInterfaceMapping
dict(
SCHEMA_NAME = 'MaterialInterfaceMapping',
DOC = '''
The MaterialInterfaceMapping schema identifies a material node
parameter using its two members 'nodePath' and 'inputName'.
See MaterialNetwork schema's documentation on its
'interfaceMappings' member for an example.
''',
MEMBERS = [
('nodePath', T_TOKEN, {}),
('inputName', T_TOKEN, {})
Expand All @@ -436,19 +482,78 @@
# materialNetwork
dict(
SCHEMA_NAME = 'MaterialNetwork',
DOC = '''
The MaterialNetwork schema is a container schema that defines a
material for a specific render context. A network is composed of
nodes, terminals, and interface mappings.
Interface mappings define the material's public UI. For example, the
following data sources define a public UI "globalVal" that maps to
two different node parameters:
ds at: material/<renderContext>/interfaceMappings/globalVal/[0]/
nodePath = Color_Manipulate
ds at: material/<renderContext>/interfaceMappings/globalVal/[0]/
inputName = adjustVal
ds at: material/<renderContext>/interfaceMappings/globalVal/[1]/
nodePath = Color_RetargetLayer
ds at: material/<renderContext>/interfaceMappings/globalVal/[1]/
inputName = valRemapAmount
The above means that the "globalVal" public UI name maps to the
following parameter data sources at:
ds at: material/<renderContext>/nodes/Color_Manipulate/parameters/
adjustVal
ds at: material/<renderContext>/nodes/Color_RetargetLayer/
parameters/valRemapAmount
See also the Material schema documentation for ASCII art diagram.
''',
SCHEMA_INCLUDES = ['{{LIBRARY_PATH}}/schemaTypeDefs'],
MEMBERS = [
('nodes', 'HdMaterialNodeContainerSchema', {}),
('terminals', 'HdMaterialConnectionContainerSchema', {}),
('interfaceMappings',
'HdMaterialInterfaceMappingsContainerSchema', {}),
('nodes', 'HdMaterialNodeContainerSchema',
dict(DOC = '''
Maps node names to material nodes. Each material node is a
container that is defined by the MaterialNode schema. The
topology of the network is expressed by the connections found on
each material node.
''')),
('terminals', 'HdMaterialConnectionContainerSchema',
dict(DOC = '''
Maps terminal names to material connections. Each connection
is a container defined by the MaterialConnection schema.
''')),
('interfaceMappings', 'HdMaterialInterfaceMappingsContainerSchema',
dict(DOC = '''
Maps interface names (public UI names) to vectors of material
node parameters. Each mapped material node parameter is a
container defined by the InterfaceMappings schema.
''')),
],
),

#--------------------------------------------------------------------------
# material
dict(
SCHEMA_NAME = 'Material',
DOC = '''
The Material schema is a container schema that provides the correct
material definition per render context.
For example, a material may specify several render contexts
like the universalRenderContext (""), Renderman ("ri"),
Storm ("glslfx"), etc. Each render context will then provide the
specific definition for the renderer, which is defined by the
MaterialNetwork schema. The universalRenderContext applies to all
renderers.
See "Custom Code: Schema Methods" section for ASCII art diagram.
''',
SCHEMA_TOKEN = 'material',
EXTRA_TOKENS = [
'(universalRenderContext, "")',
Expand All @@ -464,6 +569,67 @@
dict(GETTER = False))
),

#--------------------------------------------------------------------------
# materialOverride
dict(
SCHEMA_NAME = 'MaterialOverride',
DOC = '''
The MaterialOverride schema allows overrides to be made to the
material's public UI. Overrides can be applied to both material or
geometry scene index prim locations.
The following is an example of a material override. The data
source to author an override on the public UI name
"globalSpecularKface" would look like this:
ds at: materialOverride/interfaceValues/globalSpecularKface/value =
0.666
There needs to be an interface mapping defined for
"globalSpecularKface", which could look like this:
ds at: material/<renderContext>/interfaceMappings/
globalSpecularKface/[0]/nodePath = MaterialLayer
ds at: material/<renderContext>/interfaceMappings/
globalSpecularKface/[0]/inputName = specularKface
The above means that the "globalSpecularKface" public UI name will
map to the node parameter "specularKface", and for example, this
node parameter may already have a data source for its value:
ds at: material/<renderContext>/nodes/MaterialLayer/parameters/
specularKface/value = 0.222
After resolving the material override, the data source of the
node parameter's value is replaced by the overriding value data
source.
ds at: material/<renderContext>/nodes/MaterialLayer/parameters/
specularKface/value = 0.666
Note that the MaterialOverride schema does not specify a render
context token because material overrides are high-level and do not
need to know about implementation details--they just need to specify
an overriding data source. By contrast, the contents of a material
network do specify a render context token in order to define the
material nodes and interface mappings--you can imagine that a
Renderman vs Storm implementation of a material network would be
quite different.
See also the Material schema documentation for ASCII art diagram.
''',
SCHEMA_TOKEN = 'materialOverride',
SCHEMA_INCLUDES = ['{{LIBRARY_PATH}}/schemaTypeDefs'],
MEMBERS = [
('interfaceValues', 'HdMaterialNodeParameterContainerSchema',
dict(DOC = '''
Maps interface names (ie. public UI names) to overriding
data sources that follow the MaterialNodeParameter schema.
''')),
],
),

#--------------------------------------------------------------------------
# materialBinding
dict(
Expand Down
6 changes: 6 additions & 0 deletions pxr/imaging/hd/materialConnectionSchema.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ TF_DECLARE_PUBLIC_TOKENS(HdMaterialConnectionSchemaTokens, HD_API,

//-----------------------------------------------------------------------------

// The MaterialConnection schema defines an upstream connected node and
// output.
//
// See MaterialNode schema's documentation on its 'inputConnections' member
// for an example.
//

class HdMaterialConnectionSchema : public HdSchema
{
Expand Down
6 changes: 6 additions & 0 deletions pxr/imaging/hd/materialInterfaceMappingSchema.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ TF_DECLARE_PUBLIC_TOKENS(HdMaterialInterfaceMappingSchemaTokens, HD_API,

//-----------------------------------------------------------------------------

// The MaterialInterfaceMapping schema identifies a material node parameter
// using its two members 'nodePath' and 'inputName'.
//
// See MaterialNetwork schema's documentation on its 'interfaceMappings'
// member for an example.
//

class HdMaterialInterfaceMappingSchema : public HdSchema
{
Expand Down
39 changes: 39 additions & 0 deletions pxr/imaging/hd/materialNetworkSchema.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,37 @@ TF_DECLARE_PUBLIC_TOKENS(HdMaterialNetworkSchemaTokens, HD_API,

//-----------------------------------------------------------------------------

// The MaterialNetwork schema is a container schema that defines a material
// for a specific render context. A network is composed of nodes, terminals,
// and interface mappings.
//
// Interface mappings define the material's public UI. For example, the
// following data sources define a public UI "globalVal" that maps to two
// different node parameters:
//
// ds at: material/<renderContext>/interfaceMappings/globalVal/[0]/ nodePath =
// Color_Manipulate
//
// ds at: material/<renderContext>/interfaceMappings/globalVal/[0]/ inputName
// = adjustVal
//
// ds at: material/<renderContext>/interfaceMappings/globalVal/[1]/ nodePath =
// Color_RetargetLayer
//
// ds at: material/<renderContext>/interfaceMappings/globalVal/[1]/ inputName
// = valRemapAmount
//
// The above means that the "globalVal" public UI name maps to the following
// parameter data sources at:
//
// ds at: material/<renderContext>/nodes/Color_Manipulate/parameters/
// adjustVal
//
// ds at: material/<renderContext>/nodes/Color_RetargetLayer/
// parameters/valRemapAmount
//
// See also the Material schema documentation for ASCII art diagram.
//

class HdMaterialNetworkSchema : public HdSchema
{
Expand All @@ -61,12 +92,20 @@ class HdMaterialNetworkSchema : public HdSchema
/// \name Member accessor
/// @{

/// Maps node names to material nodes. Each material node is a container
/// that is defined by the MaterialNode schema. The topology of the
/// network is expressed by the connections found on each material node.
HD_API
HdMaterialNodeContainerSchema GetNodes() const;

/// Maps terminal names to material connections. Each connection is a
/// container defined by the MaterialConnection schema.
HD_API
HdMaterialConnectionContainerSchema GetTerminals() const;

/// Maps interface names (public UI names) to vectors of material node
/// parameters. Each mapped material node parameter is a container defined
/// by the InterfaceMappings schema.
HD_API
HdMaterialInterfaceMappingsContainerSchema GetInterfaceMappings() const;

Expand Down
3 changes: 3 additions & 0 deletions pxr/imaging/hd/materialNodeParameterSchema.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ TF_DECLARE_PUBLIC_TOKENS(HdMaterialNodeParameterSchemaTokens, HD_API,

//-----------------------------------------------------------------------------

// The MaterialNodeParameter schema defines the value data source for the
// parameter.
//

class HdMaterialNodeParameterSchema : public HdSchema
{
Expand Down
20 changes: 20 additions & 0 deletions pxr/imaging/hd/materialNodeSchema.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,20 @@ TF_DECLARE_PUBLIC_TOKENS(HdMaterialNodeSchemaTokens, HD_API,

//-----------------------------------------------------------------------------

// The MaterialNode schema is a container schema that defines a particular
// node in a material network.
//
// A material node defines its connections to other nodes via the
// "inputConnections" member. For example, "albedo" would define that it
// receives its value from its connection to the node "Color_UnPreMult" and
// the output "resultRGB" with the following data sources:
//
// ds at: material/<renderContext>/nodes/MaterialLayer/inputConnections
// /albedo/[0]/upstreamNodePath = Color_UnPreMult
//
// ds at: material/<renderContext>/nodes/MaterialLayer/inputConnections
// /albedo/[0]/upstreamNodeOutputName = resultRGB
//

class HdMaterialNodeSchema : public HdSchema
{
Expand All @@ -63,9 +77,15 @@ class HdMaterialNodeSchema : public HdSchema
/// \name Member accessor
/// @{

/// Maps parameter names to node parameters. Each node parameter is a
/// container that is defined by the MaterialNodeParameter schema. Note
/// that parameters are inputs that supply their value directly.
HD_API
HdMaterialNodeParameterContainerSchema GetParameters() const;

/// Maps input names to vectors of connections. Each connection is defined
/// by the MaterialConnection schema. Note that inputConnections are
/// inputs that get their value from data flow over the connection.
HD_API
HdMaterialConnectionVectorContainerSchema GetInputConnections() const;

Expand Down
Loading

0 comments on commit 30392d9

Please sign in to comment.