About shader_builder XML

In its most basic form, a Matchbox or Lightbox is only a .glsl file that contains all the shader information. That single file is enough for the application to generate both the shading result and a rough UI for the end user to manipulate the shader parameters.

To create a useful UI, you need a sidecar .xml file. This file is generated by running the shader_builder utility with the -x switch. Once it's been created by shader_builder, you can edit the xml to tweak the UI to your needs, such as substituting curves for numeric fields.

Note: Any uniform with a name that starts with "adsk_" is not shown in the user interface and not considered by shader_builder.

XML Structure

<!DOCTYPE ShaderNodePreset [
 
<!ELEMENT ShaderNodePreset (Shader+, Page+)>
<!ELEMENT Shader (Uniform+)>
<!ELEMENT Uniform (SubUniform* | PopEntry* | Duplicate*)>
<!ELEMENT SubUniform EMPTY>
<!ELEMENT PopEntry EMPTY>
<!ELEMENT Duplicate EMPTY>
<!ELEMENT Page (Col+)>
<!ELEMENT Col EMPTY>
]>

`<ShaderNodePreset>`

Parent

None. ShaderNodePreset is the root element.

Children

<Shader> : At least one for a Matchbox. Only one for a Lightbox . See <Shader> usage definition.
<Page>: At least one.

Usage

Root element. Mandatory.

Attribute	Description	Allowed Values	Default
Description	A description of the Preset. The description appears in the Matchbox node Note available from the Schematic.	Character data	EMPTY
Name	The name of the Preset. The name appears in the Name field of the Node interface. The Name attribute overrides the filename, so if the .xml file is present, even if the user loads the .glsl file, the Name attribute is displayed in the UI.	Character data	Name of the preset
HelpLink (optional)	Allows you to specify an URL that can be used for external documentation (only valid XML characters are allowed in the URL). A Help button is added to the Matchbox interface when this token is detected.	Character data	EMPTY
LimitInputsToTexture (optional)	Allows you to limit the number of Input Sockets on the Matchbox node to the number of textures required by your shader.	True False	False
MatteProvider	Matchbox only Specifies if the Matchbox shader provides a matte to its child node, or if it is a pass through, where the Matchbox's child node uses the matte from the Matchbox's parent. If the Matchbox operates on the alpha and you want that alpha to be passed on the child node, you must set MatteProvider = True.	True False	False
SupportsAction	Matchbox only Hints to the usage of the Matchbox, in this case as an Action node. Batch is always supported.	True False	False
SupportsTransition	Matchbox only Hints to the usage of the Matchbox, in this case as a transition in the timeline. Batch is always supported.	True False	False
SupportsAdaptiveDegradation	Matchbox only Defines if the Matchbox node supports Batch adaptive degradation. Use in combination with the adsk_degrade uniform to create a less costly data path, or even completely bypass the Matchbox to enhance Batch interactivity. Note that the Matchbox must be coded with alternate paths using the adsk_degrade for adaptive degradation to work: simply setting SupportsAdaptiveDegradation = True does not make the node turn off when adaptive degradation is turned on.	True False	False
CommercialUsePermitted	Indicates if the shader should be used for commercial purposes. This attribute is not enforced by the application. Set by the creator of the shader to indicate if the shader can be used for commercial purposes. The user of the shader is responsible for verifying this attribute and using the shader accordingly.	True False	True
AccumulatePass	Numeric value that allows the matchbox to accumulate an intermediate pass. ( ShaderIndex ) rather than the final result: One-based.
AccumulationFromStartFrame	Bool that specifies if accumulation should proceed recursively. There is an Accumulate example provided in the EXAMPLE folder.	True False	True
ShaderType	Defined by shader_builder, determines the type of shader, Lightbox or Matchbox.	Matchbox / Lightbox	Value depends on the .glsl file used to create the XML.
SoftwareVersion	Defined by shader_builder, indicates the version of the application used to build the .xml.	Character data	shader_builder defined
TimelineUseBack	Matchbox only Defines if the Matchbox uses the background of the timeline (True), or not (False). Only used in context of the timeline.	True False	True
Version	Version of shader. Metadata which is user-defined and not processed by the application.	Character data	1

`<Shader>`

Parent

<ShaderNodePreset>

Children

<Uniform> : At least one.

Usage

Mandatory.
There is one <Shader> for each shader pass defined in the .glsl file: a Matchbox can have multiple shader passes, but a Lightbox can only ever have one. <Shader> lists the uniforms required for the associated shader pass.

Attribute	Description	Allowed Values	Default
Index	The index of the associated shader pass. Indexed from 1.	Integer	1
OutputBitDepth	Bit depth of the render target for this render pass.	Output 8 16 Float16 Float32	Output
OutputWidth	Width of the render target to use for this pass if none can be determined from the inputs (non-existing or no connection). In multi-pass shader, only the last pass need specify this value. Ignored in Action and on the Timeline.	Integer
OutputHeight	Height of the render target to use for this pass if none can be determined from the inputs (non-existing or no connection). In multi-pass shader, only the last pass need specify this value. Ignored in Action and on the Timeline.	Integer
OutputWidthScaleFactor	Scale the width of the render target for this pass relative to the output resolution.	1 = no scaling 0.5 = half the size
OutputHeightScaleFactor	Scale the height of the render target for this pass relative to the output resolution.	1 = no scaling 0.5 = half the size
OutputScaleFactorEffect	Define the effect of the scale factors on the sizes.	0 = floor 1 = round 2 = ceiling
OutputNbLevels	Specify the number of levels for a custom mipmap intermediate pass.
OutputNbResults	Specify the number of textures produce by an intermediate pass.

`<Uniform>`

Parent

<Shader>

Children

<SubUniform> : As many as required by the uniform, as defined by the Type attribute, and if ValueType <> PopUp.
<PopupEntry> : Only if attribute ValueType = PopUp, in which case there can be as many as required.
<Duplicate>: Only one, only if parent <Uniform> is a duplicate. See <Duplicate> definition.

Usage

One for each uniform in the current pass.

Attribute	Description	Allowed Values
Type	Type of uniform.	float vec2 vec3 vec4 int ivec2 ivec3 ivec4 bool bvec2 bvec3 bvec4 mat2 mat3 mat4 mat2x3 mat2x4 mat3x2 mat3x4 mat4x2 mat4x3 sampler2D
Tooltip	The text for this uniform tooltip.	Character data
DisplayName	The name displayed for this uniform in the user interface.	Character data
ChannelName	The name displayed for this uniform's Animation Channel.	Character data
Name	The name of the uniform used in the GLSL file, set by shader_builder. It cannot be changed as this is used to indicate which uniform in the .glsl file uses this UI element.	Character data
Row	The row where the uniform is positioned in the UI.	0-4
Col	The column where the uniform is positioned in the UI.	0-3
Page	The page where the uniform is positioned in the UI.	0-6
Default	The default value of this uniform.	Values allowed based on type of the uniform: True or False: bool, bvec2, bvec3, bvec4 An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
Inc	The stepping used when dragging in the uniform.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
IconType	vec2/vec3 only Defines the type of icon used to control the uniform in the Viewport. Note: Only "None" and "Pick" are available in the Timeline Player. "Light" and "Axis" are automatically replaced by Pick in this case.	None Pick (Pick in the Viewport) Axis (Axis icon in the Viewport) Light (Light icon in the Viewport)
IconDefaultState	bool Defines the default On/Off state for the icon.	False (default) True
Max	Maximum allowed value for the uniform.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
Min	Minimum allowed value for the uniform.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
ResDependant	float/vec2/vec3/vec4 only Defines which resolution dependance this uniform has, if any.	None Width (values are scaled based on width) Height (values are scaled based on height)
Action3DWidgets	vec2/vec3/vec4 only Specifies that the widget is measured in Action space ( Origin is center of the image and Top Right is ( W/2, H/2) )	False (default) True
ValueType	vec3, ivec2, ivec3, ivec4 and int only XYZ/RGB/Popup modes.	Position: Values are presented as numerics. Colour: Values are presented as a colour, with a colour pot. ColourWheel: Values are presented as a HGS colour wheel. You can also name the channels with the tokens: AngleName, IntensityName1, IntensityName2. The bool HueShift tag controlls if the outer wheel rotates with the chosen Hue. ColourWheelRGBOffset: Provides a 0-based basic model.ColourWheelRGBSlope: Provides a 1.0-based model, with no negative values.ColourWheelRGBPower: Provides the inverse of Slope. PopUp: Values are presented as a popup menu. You must add a <PopupEntry> element within this <Uniform> to specify the names and their associated Int values. Curve: Values are presented as curves. The int (ivec2, ivec3 or ivec4) value is a handle on 1 (2,3 or 4) curve(s). The curve(s) can be evaluated using the function adskEvalDynCurves taking as arguments the handle and a float (vec2, vec3 or vec4) representing the point to evaluate and returning a float (vec2, vec3 or vec4) representing the output(s) of the curve(s) LargeCurve: 3-columns wide curve widget allowing you to use the Proportional mode for every curve defined, as well as an X and Y fields to edit precisely the current selection. Proportional: Position a numeric field next to its label for vec3 and vec4, allowing for larger numeric fields and a better layout.
Index	sampler2D only The position of the sampler in the user interface.	Integer
GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER	sampler2D only Interpolation modes.	GL_NEAREST GL_LINEAR GL_NEAREST_MIPMAP_NEAREST GL_LINEAR_MIPMAP_NEAREST GL_NEAREST_MIPMAP_LINEAR GL_LINEAR_MIPMAP_LINEAR
GL_TEXTURE_WRAP_T, GL_TEXTURE_WRAP_S	sampler2D only Wrapping modes.	GL_CLAMP GL_CLAMP_TO_BORDER GL_CLAMP_TO_EDGE GL_REPEAT GL_MIRRORED_REPEAT
NoInput	sampler2D only Defines the behaviour of a missing input.	Error (Generates an error) Black (Replaces missing input with Black) White (Replaces missing input with White)
Mipmaps	sampler2D only Enable to use mipmaps on this sampler. GL_TEXTURE_MIN_FILTER must be set to one of the following: GL_NEAREST_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR, GL_LINEAR_MIPMAP_LINEAR.	True False
GL_TEXTURE_BORDER_COLOR	(Optional) Allows you to specify GL_TEXTURE_BORDER_COLOR values in the "r,g,b" format.
InputType	(Optional; Matchbox only) Specifies the type of an Input socket on the Matchbox node.	Front (for red) Back (for green) Matte (for blue) Selective
InputColor	(Optional; Matchbox only) Allows you to specify a custom input tab 8-bit colour. If InputType is also specified, InputType takes precedence over InputColor. Refer to matchbox/shaders/EXAMPLES/InputSockets.xml for example.s	r,g,b values, where each component is 0-255.
UIConditionSource	(Optional) The name of the uniform used to conditionally disable or hide the current uniform in the user interface.	Name of a uniform
UIConditionValue	(Optional) The value of the UIConditionSource required for the uniform to be active.	Character data
UIConditionInvert	(Optional) Allows you to invert the logic of UIConditionValue.	True False
UIConditionType	(Optional) Allows you to choose between disabling or hiding the current uniform, based on the UIConditionSource status. Refer to matchbox/shaders/EXAMPLES/ConditionalUI.xml for an example.	Disable Hide

Example files can be found in /opt/Autodesk/presets/<application_version>/matchbox/shaders/EXAMPLES/.

The following attributes are only used to define a curve-based UI, when <Uniform ValueType = Curve>. For an example in context, see /opt/Autodesk/presets/<application_version>/matchbox/shaders/EXAMPLES/Curves.glsl.

Attribute	Description	Allowed Values	Default
CurveMinX, CurveMaxX, CurveMinY, CurveMaxY	Define the x/y range of the curves.	Float.	CurveMinX and CurveMinY: 0.0 CurveMaxX and CurveMaxY: 1.0
CurveBackground	Defines the type of background for the curve editor.	0 : empty background 1 : hue gradient background 2 : intensity gradient background	0
CurveWrapArround	Defines the behaviour of the curve(s) at the border.	0 : no wraparound 1 : wraparound	0
CurveShape	Defines the default shape of the curves.	0 : linear shape from (CurveMinX,CurveMinY) to (CurveMaxX,CurveMaxY). 1 : linear shape from (CurveMinX,CurveMaxY) to (CurveMaxX,CurveMinY). 2 : S shape. 3 : inverse S shape. 4 : constant with MaxY value. 5 : constant with MinY value. 6 : constant with MinY + 0.5*(MaxY-MinY) value.	0
CurveR	Defines the R colour of all the curves attached to this uniform.	Integer	0
CurveG	Defines the G colour of all the curves attached to this uniform.	Integer	0
CurveB	Defines the B colour of all the curves attached to this uniform.	Integer	0

`<SubUniform>`

Parent

<Uniform>

Child

EMPTY

Usage

There is one <SubUniform> element for each value required by the <Uniform> parent, based on the Value attribute: vec3 requires 3 <SubUniform>, float requires none. How this gets translated in the UI depends on the ValueType defined: Colour displays a colour pot, which means that the SubUniform defines the starting RGB values for that uniform, whereas Position with a vec3 displays three numeric fields defined by the attributes of 3 <SubUniform>.

Attribute	Description	Allowed Values
Default	The default value of the parent uniform.	Values allowed based on type of the uniform: True or False: bool, bvec2, bvec3, bvec4 An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
Inc	The stepping used when dragging in the SubUniform. Overrides the <Inc> defined in the parent <Uniform>.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
Max	Maximum allowed value for the SubUniform.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
Min	Minimum allowed value for the SubUniform.	Values allowed based on type of the uniform: An Integer: int, ivec2, ivec3, ivec4 A Float: float, vec2, vec3, vec4, mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3
ResDependant	float/vec2/vec3/vec4 only Defines which resolution dependance this uniform has, if any.	None Width (values are scaled based on width) Height (values are scaled based on height)

The following attributes are only used to define a curve-based UI, when <Uniform ValueType = Curve>. These values override the more general values from the parent <Uniform>.

Attribute	Description	Allowed Values	Default
CurveMinX, CurveMaxX, CurveMinY, CurveMaxY	Define the x/y range of the curves.	Float.	CurveMinX and CurveMinY: 0.0 CurveMaxX and CurveMaxY: 1.0
CurveBackground	Defines the type of background for the curve editor.	0 : empty background 1 : hue gradient background 2 : intensity gradient background	0
CurveWrapArround	Defines the behaviour of the curve(s) at the border.	0 : no wraparound 1 : wraparound	0
CurveShape	Defines the default shape of the curves.	0 : linear shape from (CurveMinX,CurveMinY) to (CurveMaxX,CurveMaxY). 1 : linear shape from (CurveMinX,CurveMaxY) to (CurveMaxX,CurveMinY). 2 : S shape. 3 : inverse S shape. 4 : constant with MaxY value. 5 : constant with MinY value. 6 : constant with MinY + 0.5*(MaxY-MinY) value.	0
CurveName	The name of the curve represented by this SubUniform.	Character data
CurveR	Defines the R colour of this SubUniform's curve.	Integer	0
CurveG	Defines the G colour of this SubUniform's curve.	Integer	0
CurveB	Defines the B colour of this SubUniform's curve.	Integer	0

`<Duplicate>`

Parent

<Uniform>

Children

EMPTY

Usage

When a uniform is present in more than one shader pass, it is only shown once in the user interface. This is indicated by the <Duplicate> element.

For example, if a two-pass preset uses a bool uniform named filtering, the XML file defines it in the first <Shader> element:
```
<Uniform Row="0" Col="0" Page="0" Default="True" Tooltip="" DisplayName="Filtering" Type="bool" Name="filtering">
</Uniform>
```
In the second <Shader> element, it is defined as a duplicate.
```
<Uniform Type="bool" Name="filtering">
<Duplicate>
</Duplicate>
</Uniform>
```
If the second uniform isn't defined as a duplicate, it appears twice in the node UI.

Attributes

NONE

`<PopupEntry>`

Parent

<Uniform>

Children

EMPTY

Usage

Only used if <Uniform ValueType = Popup>. Each <PopupEntry> is an element of the drop-down list.
```
<PopupEntry Title="ReplaceMe" Value="0">
</PopupEntry>
```
Refer to /opt/Autodesk/presets/<application_version>/matchbox/shaders/EXAMPLES/BuildList.xml for an example.

Attribute	Description	Allowed Values
Title	The entry displayed in the drop-down list.	Character data
Value	The actual value passed to the uniform.	Character data

`<Page>`

Parent

<ShaderNodePreset>

Children

<Col> : Up to 6 children.

Usage

Defines the name of a page, and the index of that page. A page can have two states in the UI: expanded or collapsed, as decided by the user.

If a UI page is expanded, it displays all 6 children <Col> of this <Page> element. In this case, the name displayed in the UI is defined by the Name property.

If the UI page is collapsed, then the 6 <Col> of this <Page> element are automatically split over two UI pages. One page name is defined by ColName0_2 and contains the first three <Col>. The other page name is defined by ColName3_5 and contains the last three <Col>. First to last order defined by the Index property of each <Col>.

Attribute	Description	Allowed Values	Default
Name	Name of the page in the UI. Used when all the columns are displayed at once in the Expanded UI.	Character data	Page 1
ColName0_2	Name of the page in the UI, used for the page that contains the first 3 columns of the shader settings. For use in the collapsed UI.	Character data	Page 1
ColName3_5	Name of the page in the UI, used for the page that contains the last 3 columns of the shader settings. For use in the collapsed UI.	Character data	Page 2
Page	Index of the page.	Indexed from 0, max value of 6.	0

`<Col>`

Parent

<Page>

Children

EMPTY

Usage

Defines the name of a column within a page.

Attribute	Description	Allowed Values	Default
Name	Name of the column to be displayed in the UI.	Character data	Column 1
Col	Index of the column.	Indexed from 0, max value of 6.	0
Page	Index of the <Page> where the column appears.	Indexed from 0, max value of 6.	0

About shader_builder XML

XML Structure

<ShaderNodePreset>

<Shader>

<Uniform>

<SubUniform>

<Duplicate>

<PopupEntry>

<Page>

<Col>

Was this information helpful?

`<ShaderNodePreset>`

`<Shader>`

`<Uniform>`

`<SubUniform>`

`<Duplicate>`

`<PopupEntry>`

`<Page>`

`<Col>`