mental mill User Guide Document version 1.33 June 17, 2010

Transcription

1 mental mill User Guide Document version 1.33 June 17, 2010

2 Copyright Information Copyright c mental images GmbH, Berlin, Germany. All rights reserved. This document is protected under copyright law. The contents of this document may not be translated, copied or duplicated in any form, in whole or in part, without the express written permission of mental images GmbH. The information contained in this document is subject to change without notice. mental images GmbH and its employees shall not be responsible for incidental or consequential damages resulting from the use of this material or liable for technical or editorial omissions made herein. mental images, mental ray, mental matter, mental mill, mental queue, mental cloud TM, mental mesh, mental ray Phenomenon TM, RealityServer, RealityPlayer, RealityDesigner, MetaSL, Metanode, Phenomenon TM, neuray, iray, DiCE TM, IRP TM, imatter, Shape-By-Shading, SPM, and rendering imagination visible TM are trademarks or, in some countries, registered trademarks of mental images GmbH, Berlin, Germany. Other product names mentioned in this document may be trademarks or registered trademarks of their respective companies and are hereby acknowledged. mental mill User Guide, doc Copyright c 2010 mental images

3 Table of Contents Table of Contents New Features for Standard Edition Graph View Workflow Improvements 1 Scrolling node parameters 1 Grouping parameters 1 Changing the size of nodes 1 Reordering Phenomenon parameters 2 Reducing wires in your workspace 2 Selecting and deselecting wires 2 Selecting parameters 2 Using the contextual menu 2 Using the Attach by name... command 3 Highlighting compatible attachments 3 Renaming parameters 3 Parameter Editor 3 Struct and array parameters 3 Parameter groups 3 About parameter states 4 Types of parameter states 4 Changing a parameter state 4 Shader Toolbox 5 Toolbox filters 5 New mental mill Phenomena 6 Material definitions 6 New mental mill shaders 7 Shader Manager 8 MetaSL 1.1 compiler 9 New custom preview geometry 9 Workspaces 9 New textures 10 Miscellaneous 10 Introduction to mental mill Standard Edition 11 About mental mill Standard Edition 11 About shader nodes 12 More information 12 Shader creation overview 12 Nodes 13 Adding a node to the Graph View 14 Building a Shader Graph 14 Connecting two shader nodes with an attachment 14 View of two attached shader nodes 15 Copyright c 2010 mental images mental mill User Guide, doc i

4 Table of Contents Connecting shader nodes with the Parameter Editor 15 Disconnecting two shader nodes 15 Shader node attachment restrictions 16 View of a Shader Graph 16 Creating a Phenomenon 17 Creating a Phenomenon from a Shader Graph 17 View of a closed and open shader 17 Creating an empty Phenomenon 17 Creating a Phenomenon from a Phenomenon 17 About attaching parameters to a Phenomenon 18 Attaching input parameters to a Phenomenon 18 Attaching output parameters to a Phenomenon 18 Recommendations 19 Grouping parameters 19 View of parameter grouping 19 Creating parameter groups for a MetaSL shader 19 Creating parameter groups for Phenomenon or Material Definitions 19 Manipulating nodes in the Graph View 20 Creating and manipulating nodes 20 Editing input parameters 25 Manipulating Phenomena 32 Reordering interface parameters 36 Creating a parameter group for a Phenomenon or material definition 36 Attaching sub-shaders 37 Exporting the shader 37 Creating material definitions 43 Creating a material definition 44 Creating a material definition from a Toolbox preset 44 Creating a material definition from the graph view 44 Extending a material definition 45 Evaluating the BSDF in the surface subgraph 46 A note about the material component link 46 Undo and redo 47 Output preview 47 How to view individual output values 48 How to set preview rendering preferences 54 Render scene settings 54 Render preview 56 Animation 58 Debugging shaders 58 Code view 59 Parameters 60 ii mental mill User Guide, doc Copyright c 2010 mental images

5 Table of Contents Editor preferences 61 Saving project files 61 Exploring the toolbox 61 Customizing the toolbox 62 Toolbox commands 62 Using the toolbox filters 63 Adding a Phenomenon to the toolbox 64 Editing a Phenomenon stored in the toolbox 64 Exploring the Shader Manager 64 Using the search field 65 About predefined search criteria 65 Displaying predefined search criteria 65 About matching search terms 65 Displaying source paths and file names in your search requests 65 Keeping references to shaders in a project 66 Path setting 66 Application data 67 Log window 68 System diagnostics 68 Sample project files 68 Copyright c 2010 mental images mental mill User Guide, doc iii

6 Table of Contents iv mental mill User Guide, doc Copyright c 2010 mental images

7 New Features for Standard Edition 1.1 Graph View Workflow Improvements New Features for Standard Edition 1.1 This chapter describes the new features available in mental mill Standard Edition version 1.1. Graph View Workflow Improvements Scrolling node parameters You can control: The node splitter position that divides the node into independent input and output parameter sections Output parameter view areas The size of nodes To activate the splitter mode, hold down the Shift key while resizing the node with the mouse. You must resize from the top or bottom of the node to activate this mode. Resizing the left and right sides of the node does not activate the splitter mode. To de-activate the splitter mode, double click anywhere on the node. The node is displayed in its default size. When the splitter mode is active, you can drag the horizontal splitter bar to resize the top and bottom parts of the node. You can partially, or completely hide the parts of the node. When information is partially obscured, a scroll bar is displayed to enable you to view hidden information. Grouping parameters You can group input and output parameters to improve the organization of your workspace. You can choose to: Define groups directly in the MetaSL source code Create groups dynamically for Phenomena within the mental mill application To display specific parameter groups, you can expand or collapse groups. Note: You can nest parameter groups at any depth. Changing the size of nodes Changing the size of nodes is intuitive as it follows a standard scheme. To size graph nodes, simply click and drag any of the four sides or corners of a node. Note: When you expand or collapse parameter preview windows or parameters with child components such as struct, array or groups, this automatically resizes the node. Tip: To obtain a better graph layout inside Phenomena, position the parameters of open nodes vertically. Copyright c 2010 mental images mental mill User Guide, doc

8 New Features for Standard Edition 1.1 Graph View Workflow Improvements Reordering Phenomenon parameters To reorder phenomenon input and output parameters interactively, drag a parameter and then drop it in a new location or parameter group. Reducing wires in your workspace When a parameter group is collapsed, all attachment wires originating from parameters in the group are combined. Multiple wires connecting two closed groups are combined into a single wire. When an attachment wire is hidden at one or both ends, the wire is partially transparent. This is to reduce the amount of wires displayed inside the workspace. Selecting and deselecting wires When you select a wire, it is highlighted. This makes the wire easier to distinguish from the other wires displayed. To deselect a wire, click on any empty area in the graph view workspace. Ctrl + click toggles the selection on and off and allows the selection of multiple wires. Pressing the delete key deletes all selected wires and possibly, selected nodes. Selecting parameters To select Individual parameters Ranges of parameters You need to Press the Ctrl key and then the left mouse button. Press the Shift key and the left mouse button and then select a range of parameters. Using the contextual menu You can now use the context (right-click) menu available in the input and output area of a node to: Select all parameters, deselect all parameters, or invert parameter selections Expand and collapse parameters that are groups, structs or arrays Add parameters to a Phenomenon interface by selecting a range of parameters and then adding them to the Phenomenon interface Remove parameters from a Phenomenon interface 2 mental mill User Guide, doc Copyright c 2010 mental images

9 New Features for Standard Edition 1.1 Parameter Editor Using the Attach by name... command If you have several nodes with an input parameter called, for example, Amount, you can connect an interface parameter to all of these input parameters in one go. To do this, follow these steps: 1. Right-click the connection box of your interface parameter. 2. Select Attach by name... A dialog box is displayed. 3. Enter Amount in the field. All the input parameters called Amount are connected to the interface parameter. This provides you with a single parameter to drive the inputs of this Phenomenon. Highlighting compatible attachments Compatible attachment points are highlighted in green when you click an input or output attachment point to begin an attachment. It enables you to locate an attachment of the same type more easily. Renaming parameters To rename parameters, double-click a Phenomenon input or output parameter. The Rename Parameter dialog box displays. Parameter Editor The Parameter Editor contains the following new features: Struct and array parameters Parameter groups Parameter states Struct and array parameters You can now edit parameters that have struct or array types directly in the Parameter Editor. You can expand them to access the struct members or array elements. MetaSL supports nested structs and arrays, and the Parameter Editor also supports this. A size button is available for dynamic arrays and this enables you to specify the array size. Parameter groups Parameter groups provide a level of organization for the Parameter Editor. You can expand or collapse Parameter groups in the Parameter Editor. This enables you to focus on the parameter groups that you are interested in within a shader containing a large number of parameters. Copyright c 2010 mental images mental mill User Guide, doc

10 New Features for Standard Edition 1.1 Shader Toolbox About parameter states You can control the state of each parameter using the Parameter Editor. For example, you can: Set a parameter state to a literal value that you edit in the Parameter Editor Attach a parameter state to the output of another node or Phenomenon Inherit a default value from the class default value of a shader, rather than retrieving the parameter values from a node connection or from the parameter editor Create attachments directly in the Parameter Editor (rather than clicking and dragging attachments from the Graph View). Types of parameter states The following list provides you with details about the parameter states that you can control in the Parameter Editor. Inherit parameter PARAMETER NAME: When a parameter is in inherit mode, you can no longer change it. Instead, it provides the class value for the parameter which is the default initialization. You can open the context menu by clicking an icon on the right side of the parameter field. Attach parameter PARAMETER NAME: Connects the parameter to the output of another node. You can use this parameter to connect the parameter to a node that is currently not visible on the workspace. Detach parameter PARAMETER NAME: Disconnects a parameter from the node that it is connected to. This option only appears when the parameter is in an attached state. Reset parameter PARAMETER NAME: Resets the value to the default initialization value. Update parameter PARAMETER NAME default value: This only concerns Phenomena. It sets the current parameter value as the default class value for the given Phenomenon interface parameter. The current parameter value becomes the new default value that is used when the parameter is reset or changed to inherit mode. Changing a parameter state Follow the steps below to control the parameter states: Open the parameter editor and right-click a parameter. A context menu displays. Select a parameter state from the list. 4 mental mill User Guide, doc Copyright c 2010 mental images

11 New Features for Standard Edition 1.1 Toolbox filters Shader Toolbox The mental mill Toolbox has changed and contains the following new palettes: utilities material presets texture utilities animated This section describes these new palettes. utilities palette The Utilities folder contains Phenomena that help you to handle recurring tasks such as: Compositing reflections Creating perturbed surface normals from a normal map Mixing two bump maps, and so on For a description of the new Phenomena, see page 6. material presets palette The Material presets folder contains predefined material templates that enable you to use MetaSL 1.1 BSDF types and expose their parameters in the material interface. These templates are a good starting point for you to begin extending and creating more complex shader networks based on the material definitions. texture utilities palette The Texture utilities folder contains Phenomena that enable you to edit and manipulate several UV coordinate tasks. If you navigate to the project file texture edit examples.xmsl in the mental mill projects folder, you can view use-cases for these Phenomena. For a description of the new Phenomena, see page 6. animated palette Contains all mental mill base shaders that provide animation over time. Toolbox filters A set of Toolbox filters is now available. These filters will help you to navigate through the mental mill shader library. They are continually applied to the Toolbox, which updates dynamically when a relevant change is made. The following table describes the Toolbox filters: Copyright c 2010 mental images mental mill User Guide, doc

12 New Features for Standard Edition 1.1 Material definitions Filter Hide default shader classes Hide built-in shader classes Hide user-defined shaders Hide Phenomena Hide shaders not in default path Description Only displays shaders that you have added to the Toolbox. Hides shaders that are generated internally and have no corresponding MetaSL source code file. Hides shaders that you have added to the Toolbox. Shows only shaders that are not Phenomena. Shows only shaders whose MateSL shader files are located in the user shader path. New mental mill Phenomena mental mill 1.1 includes a selection of predefined Phenomena that facilitate shader creation. The following table provides you with a list of the Phenomena that have been added to the mental mill Toolbox and a brief functional description. Phenomenon Description Texture lookup extended A versatile texture lookup Phenomenon. It bundles a lot of functionality into a single node. Generic reflection Adds a reflection on top of the input Base Color. Color and falloff of the reflection can be easily adjusted. Normals normalmap Consolidates texture lookup and normal generation for normal mapping into a single node. Dual bump mixer Mixes two bump maps. Provides control to adjust the intensity of each bump map as well as blending between the two maps. Reflection vector Generates a reflection vector. Alpha remapping Adds control for various alpha channel manipulations. UV edit Consolidates rotation, scaling and offsetting UV coordinates into one node. UV mirror Mirrors the UV coordinates. Mirroring can be defined separately for U and V. UV tile Repeats the fractional part of the UV coordinates so that the UV coordinates remain within the range UV placement Creates a sub-projection on the UV coordinates. Lets the user specify position and size. Outputs the new UV coordinates as well as a Boolean mask for compositing. UV animate Continuously offsets the UV space. Speed for U and V offset can be set separately. Note: For a complete description of the shaders and their parameters, go to the main menu in mental mill SE and select Help > Shader Library. Material definitions mental mill supports MetaSL 1.1 material definition, a named shader graph created to define a material. 6 mental mill User Guide, doc Copyright c 2010 mental images

13 New Features for Standard Edition 1.1 New mental mill shaders The Graph View provides a contextual (right-click) menu command. Using this command, you can create a new material definition that is preconfigured with a specific MetaSL 1.1. compliant BSDF type. mental mill provides you with predefined material templates that are available in the default Shader Toolbox, inside the material presets folder. The material presets folder contains the following templates: Phong basis material Oren nayar basis material Ashikhmin shirley basis material Lambert basis material These templates use MetaSL 1.1 BSDF types and expose their parameters in the material interface. You can assign material definition components by creating an attachment. This is achieved in the same way as you establish other connections in mental mill. New mental mill shaders The following table provides you with more information about the new mental mill shaders. Toolbox Shader name palette Description Layer add layer Adds foreground and background color. Layer blend Blends linearly between the foreground and background color. Layer multiply Multiplies the foreground and background color. Normals height bumpmap normals Generates a perturbed surface normal from a gray scale height-map. Generator cellular Generator cloud Generator fractal generators These nodes have a new input parameter group called Advanced that contains fixed noise and gradient tables for the shaders. Generator marble Generator noise Generator noise 4d Generator turbulence Generator wood Copyright c 2010 mental images mental mill User Guide, doc

14 New Features for Standard Edition 1.1 Shader Manager Toolbox Shader name (cont.) palette (cont.) Description (cont.) Surface components Surface direct indirect illumination components Provides separate output results for diffuse, glossy and specular light for direct and indirect illumination. Note: Some BSDF shaders may not generate a result for certain components such as the specular output. Note: To ensure that your shader works correctly, it must be used in a shader graph that is connected to the surface slot inside a material definition. Merges diffuse, glossy and specular into one result output. Provides separate outputs for direct and indirect illumination. Note: To ensure that your shader works correctly, it must be used in a shader graph that is connected to the surface slot inside a material definition. Texture coordinate 2d scale texture Scales the input texture coordinates by the scaling factors U and V scale. Texture lookup 2d alpha Has a separate float output for the alpha channel. The default value for the alpha is set to constant 1. Important: The Normals parallax shader has been removed from the Toolbox. It has been replaced with a Phenomenon that creates the same effect. Shader Manager The Shader Manager enables you to: Search the Toolbox for shaders Locate the shader files in which shaders are defined Perform other tasks to manage the shader library that is available in the Toolbox The following table describes the key features of the Shader Manager: Shader Manager feature Improved search Predefined searches Save search history Display the file path Multi-select and move folders Description Matches any or all keywords. Performs searches based on criteria other than the shader name. These searches include finding shaders that are: Broken or missing; used in your current project; selected in the Toolbox; not assigned to any Toolbox folder Saves recent searches for future use. Optionally displays the file path for the source.msl file where the shader is defined. Select multiple Toolbox folders and move them to a new location. 8 mental mill User Guide, doc Copyright c 2010 mental images

15 New Features for Standard Edition 1.1 MetaSL 1.1 compiler MetaSL 1.1 compiler mental mill 1.1 includes support for MetaSL 1.0 and 1.1 shaders. New custom preview geometry mental mill is now available with three different.obj files that can be used as custom preview geometry. File name bust.obj fancy sphere.obj mi sphere.obj Description A model of a bust, suited to develop and test shaders. The geometry from the mental mill splash screen which is useful for inspecting reflections or ambient occlusion. The preview geometry from the MetaSL shader library. Allows you to inspect all aspects of the visual properties of a shader. These files are available in the mental mill installation directory under <MILL INSTALL DIR>/data/objects. Workspaces The sample projects that ship with mental mill have been extended to include the new material definition workflow. For a complete explanation of material definitions see page 43. The following table provides you with a description of the new material definitions. Material definition Description bump map.xmsl Upgrades the bump map Phenomenon to a material definition. The result of the bump map Phenomenon is fed into a material definition with its normal parameter exposed. energy particles.xmsl Demonstrates nested Phenomena. Simulates the energy field between two charged particles. A 1D texture is used to colorize the result. eroding.xmsl Shows how to create an erosion effect by blending multiple diffuse and normal maps. The mixing values are based on a Phenomenon that calculates the distance from a point in space and that can positioned freely. material definition example.xmsl Demonstrates how to link different shader branches to the inputs of the material definition. In this particular example the transparency and the index of refraction (IOR) are controlled by textures. normal map.xmsl Demonstrates the use of the surface normal for bump-mapping with the Phong material definition. Copyright c 2010 mental images mental mill User Guide, doc

16 New Features for Standard Edition 1.1 MetaSL 1.1 compiler Material definition (cont.) material wood.xmsl parallax phen.xmsl scoreboard.xmsl splash screen decal.xmsl texture edit examples.xmsl waterflow.xmsl Description (cont.) Shows how to create a wood material that allows you to add a dirt layer. This material uses textures for the diffuse, specular and bump maps that are bundled with the mental mill 1.1 release. The mental images homepage ( contains a video tutorial that explains how to create the complete material. Shows a material definition that uses parallaxed UV coordinates for texture lookups. Parallax Uvs are generated using the Texture coordinate 2d parallax shader. Using parallax mapping enhances the illusion of perceived depth on a flat surface. Uses a number of math nodes and the underlying UV space to generate the shape of small led lights. An input image is processed, tinted and finally mixed with the generated led pattern to produce the final result. Everything is wrapped in a Phenomenon that lets the user adjust all different aspects of the LED effect. Places a decal on top of a material. This example uses some of the newly built-in Phenomena as well as the new interface parameter grouping feature. Shows use cases for the texture utility Phenomena available in the Toolbox under texture utilities. Shows two layered bump maps, one of which is animated to create the effect of water flowing down a surface. You must start the animation to see the effect. New textures You can find the new textures in the mental mill texture directory under <MILL INSTALL DIR>/data/textures. The following table provides you with a list of the new textures. New Texture wood beech diffuse.png wood beech spec.png wood beech normal.png Description Diffuse wood texture Specular wood texture Wood normal map Miscellaneous Support for MetaSL 1.1 texture properties such as width, height, and depth. Custom HLSL export: Microsoft SAS support for improved export to Autodesk Softimage. Export plugin for Autodesk 3ds Max 2011 (slate extension). Windows only. It encapsulates the selected node in a Phenomenon (.xmsl file), which is then instantiated in 3ds Max. Any values you set in the node in mental mill will be defaults when the node is instantiated in 3ds Max. 10 mental mill User Guide, doc Copyright c 2010 mental images

17 Introduction to mental mill Standard Edition About mental mill Standard Edition Introduction to mental mill Standard Edition This document explains how to use the mental mill standalone application. It is intended for shader creators, such as artists and shader writers, who know about the concept of shaders and Phenomena and who are familiar with the rendering of shaders. Knowledge about particular types of shaders such as light shaders, texture lookup shaders, and reflection models, would also be helpful. However, it is not necessary to have experience writing shader code to use this guide. About mental mill Standard Edition mental mill allows you to create shaders in an easy, intuitive way. The basic building block of shader creation is a shader node or a shader graph node. There are three different types of nodes, which you can manipulate in similar ways. These nodes are: Shader nodes Phenomenon Material Definitions The following image describes the Graphical User Interface (GUI) of the mental mill application. The menu bar that is located at the top of the GUI provides menus for loading, saving, editing, viewing, and previewing the rendering of shaders. It also contains a help section. Copyright c 2010 mental images mental mill User Guide, doc

18 Introduction to mental mill Standard Edition Nodes GUI Element Description 1. Shader node A shader node is yellow and represents a MetaSL shader. 2. Parameter Editor You can edit shader node input parameters with the Parameter Editor. 3. Phenomenon A Phenomenon is blue. A Phenomenon is a container for other shader nodes. When you open a Phenomenon, its shader graph displays. 4. Material Definition A Material Definition is green. A Material definition bundles the fundamental shading characteristics of a shader into a single node. Unlike a Phenomenon however, a Material definition has no output parameters. 5. Shader Manager Provides search functionality and predefined searches. 6. Toolbox filters Enables you to filter the toolbox using filtering criteria. 7. Toolbox Provides a large selection of node classes. 8. Graph View Area for working with shaders. About shader nodes To instantiate a shader node, select a shader inside the Toolbox and double-click it, or drag and drop one from the Toolbox onto the Graph View. Each shader node contains input and output parameters. You can edit the input parameters by using the Parameter Editor that is located in the top right corner of the GUI. You can use a shader as a standalone entity, or you can combine several shaders and work with them inside a Shader Graph, which you can then wrap inside a Phenomenon. More information For details about: Creating and manipulating Phenomena, see page 17 Material Definitons, see page 43 Shader creation overview This section briefly describes the steps to create and save a shader inside the Toolbox. These key steps are developed in the next sections of this guide. 1. Create a shader node in the Graph View. Drag and drop a shader onto the Graph View or double-click a shader inside the Toolbox. 2. Connect multiple shader nodes to form a Shader Graph. 3. Manipulate the shader nodes in the Graph View using the Parameter Editor. 4. View your changes in realtime inside the Preview window of the node. 5. Wrap your shader inside a Phenomenon, a single node that hides all underlying complexity. 6. Expose a set of parameters to the interface. 7. Save the Phenomenon in the Toolbox. 12 mental mill User Guide, doc Copyright c 2010 mental images

19 Introduction to mental mill Standard Edition Adding a node to the Graph View Nodes Shader nodes, Phenomenon, and Material Definitions are all nodes within the mental mill application. You can resize, connect, open and close these nodes in the same way. The following image shows a shader node and describes the main parts of its GUI. GUI Element Description 1. Node name Displays the name of the node. 2. Top bar Moves the node. Contains a right-click context menu. 3. Open/close button Opens or closes the node. Depending on the type of node you are using, the shader debugger or the shader graph displays. 4. Maximize/unmaximize button Opens or closes the node to its maximum or minimum size. Depending on the type of node you are using, the shader debugger or the shader graph displays. 5. Preview window A preview of the shader output parameter. To collapse the preview window, click the output parameter name. 6. Output parameter You can connect output parameters to input parameters. 7. Bottom bar Moves the node. Contains a right-click context menu. 8. Input parameter port Attachment point where you connect the output parameter of one node to the input parameter of another node. Values can be set in the Parameter Editor. 9. Input parameter group A collapsible group containing one or more input parameters. You can use this to stucture the input parameters of a shader. See also page Splitter bar Divides the node into an input parameter section and an output parameter section. When parts of the input or output parameter section are hidden, move the splitter bar to display these areas. Copyright c 2010 mental images mental mill User Guide, doc

20 Introduction to mental mill Standard Edition Building a Shader Graph Adding a node to the Graph View To add a shader node to the Graph View, you can: Drag and drop a shader from the toolbox to the Graph View. Note: To display the toolbox, use the shortcut keys Ctrl-Alt-T or choose View >Toolbox. Double-click a shader in the Graph View Use the Shader Manager beneath the toolbox to find a shader. Double-click or drag and drop the result to the Graph View. Use the right-click context menu directly inside the Graph View, and then select shaders from the shader menu that opens. For more details about the shaders and shader categories, go to the mental mill Help menu, and select Shader Library. Building a Shader Graph mental mill provides you with a large number of shader nodes to work with. To create advanced shader effects, you need to connect several shader nodes. This section explains how to do this, by attaching nodes, or by using the Parameter Editor. Connecting two shader nodes with an attachment 1. Drag and drop several shaders onto the Graph View. 2. Click the output parameter port of a shader node, hold down the left button of your mouse, and then drag the attachment to the input parameter port of another shader node. 3. Release the mouse button to connect the two shader nodes. Note: When you press the button of your mouse and hold it down, some input parameters are highlighted in green. Green attachments correspond to the input parameters that you can attach your output to. 14 mental mill User Guide, doc Copyright c 2010 mental images

21 Introduction to mental mill Standard Edition Building a Shader Graph View of two attached shader nodes The figure below shows two attached shader nodes. When two shader nodes are attached: A black dot displays inside the connection ports of the two shaders The shaders are connected by an attachment wire The connected output of one shader node controls the input parameter values of the other shader node Connecting shader nodes with the Parameter Editor 1. Open the Parameter Editor from the View menu, or press Ctrl + E. 2. Select the shader node you want to attach a parameter to. 3. Right-click the parameter in the Parameter Editor. A dialog box opens. 4. Select Attach parameter parametername, and from the submenu select a shader node output. Note: The option is grayed when there are no shader nodes with compatible outputs. Disconnecting two shader nodes 1. Left-click the attachment port of an input parameter. 2. Drag the attachment to an empty part of the Graph View. 3. Release the left mouse button. The nodes disconnect. Copyright c 2010 mental images mental mill User Guide, doc

22 Introduction to mental mill Standard Edition Building a Shader Graph Shader node attachment restrictions This section explains some of the restrictions of shader node attachments. You can only create attachments between parameters of the same type You can only attach shaders that are contained in the same Phenomenon or that are top-level shader nodes Each shader node can have multiple attachments You can use an output shader node as an input shader to several other shader nodes You can attach an input parameter to only one other output parameter of a different shader node Attachments should not create a cycle inside a Shader Graph Each structure member or array element of input parameters that are structures or arrays have their own attachment point. You can connect these attachments to other nodes. View of a Shader Graph The following example shows several attached shaders within a Shader Graph structure. 16 mental mill User Guide, doc Copyright c 2010 mental images

23 Introduction to mental mill Standard Edition Creating a Phenomenon Creating a Phenomenon A Phenomenon is a container that encapsulates several shaders. From the outside, a Phenomenon behaves like a simple shader node with input and output parameters. On the inside however, it contains a network of shader nodes that you can add or remove as you build your Phenomenon. You can store your Phenomena in the Toolbox and reuse it within any other shader project. Creating a Phenomenon from a Shader Graph 1. In the Graph View, select the shader nodes that you want to wrap inside a Phenomenon. 2. Right-click an empty area of the Graph View, and from the context menu select Create new Phenomenon from selection. A new Phenomenon displays. All of the selected shader nodes are moved inside the Phenomenon. To view the shader nodes, left-click the open/close or maximize/unmaximize button in the top right corner of the Phenomenon node. View of a closed and open shader When you create a Phenomenon it is closed (see the left image above). When you open or maximize a Phenomenon, its contents display (see the right image above). You can pan or zoom the graph inside the Phenomenon. Creating an empty Phenomenon Right-click an empty area of the Graph View and select "Create new Phenomenon" from the context menu Creating a Phenomenon from a Phenomenon You can extend the functionality of an existing Phenomenon without modifying the original one. To do this, you need to clone or copy the Phenomenon. 1. Create an instance of the Phenomenon that you want to copy on the Graph View. Copyright c 2010 mental images mental mill User Guide, doc

24 Introduction to mental mill Standard Edition Creating a Phenomenon 2. Right-click the top or bottom bar of the Phenomenon. 3. From the context menu, choose "Clone nodes class Phenomenon class". 4. Enter a class name for the Phenomenon. A new Phenomenon with a unique class name is created. This means that if you make changes to this Phenomenon, your changes will not affect the Phenomenon you copied it from. About attaching parameters to a Phenomenon When you create a Phenomenon, you must set up its input and output parameters. A Phenomenon can have any number of input or output parameters. These parameters interface with the shader nodes contained inside the Phenomenon. Attaching input parameters to a Phenomenon Input parameters allow you to modify the values inside a Phenomenon. To expose an existing parameter to the interface, follow the steps below. 1. Open the Phenomenon to view its Shader Graph. 2. Locate a node inside the Phenomenon that has an unconnected input parameter. 3. Right-click the parameter and select Add Parameter name to Phenomenon name. An input parameter can be connected to several shader nodes inside a Phenomenon. For more methods about creating input parameters, see page 35. Attaching output parameters to a Phenomenon A Phenomenon must have at least one output parameter. To attach an output parameter to a Phenomenon, follow the steps below. 1. Open or maximize a Phenomenon. 2. Locate the node that you want to connect the output parameter to. 3. Left-click the result parameter of the node and drag and drop the attachment to the output parameter of the Phenomenon. Alternatively, you can: Right-click an output parameter of a shader node inside the Phenomenon and select Add "paramater name" to "phenomenon name". A new output parameter with the correct data type will be created. Right-click the top or bottom bar of the Phenomenon. From the context menu choose "New output paramer > parameter type". 18 mental mill User Guide, doc Copyright c 2010 mental images

25 Introduction to mental mill Standard Edition Manipulating nodes in the Graph View Recommendations Whether you create an empty Phenomenon or a Phenomenon from a selection, mental mill automatically creates an output called result. You are strongly recommended to ensure that a Phenomenon has at least one output parameter called result. Grouping parameters You can create groups for parameters that you often or rarely use in mental mill. In the Parameter Editor, you can fold groups and collapse them individually. View of parameter grouping The following image shows an example of a Phenomenon that contains parameter grouping. Creating parameter groups for a MetaSL shader You can group input parameters using the in group("<group NAME>") statement. See the MetaSL specification for further details. Creating parameter groups for Phenomenon or Material Definitions You can group shader parameters using the mental mill GUI. See page 36. Copyright c 2010 mental images mental mill User Guide, doc

26 Introduction to mental mill Standard Edition Creating and manipulating nodes Manipulating nodes in the Graph View The following table provides you with an overview on how to manipulate nodes inside the Graph View. Step Create a node Rename a node Open/close parameters Select/deselect parameters Add state parameters Remove state parameters Select nodes Select all nodes Move nodes Resize a node Delete nodes Cut nodes Copy nodes Paste nodes Action Use the context menu (right-click) in the Graph View, or use the toolbox. Use the context menu (right-click) in the title bar. Left-click the parameter name. Right-click a parameter label and from the context menu choose Select all parameters or Deselect all parameters. Use the context menu (right-click) in the input parameter area. Use the context menu (right-click) on the state parameter name in the node. Left-click one node, or left-click in the Graph View and drag a group of nodes. Choose Select All from the Edit menu, or press Ctrl+A. Select nodes, left-click the title bar of any selected node, and drag it inside the Graph View. Left-click and drag a lower corner of the node. Select nodes and choose Delete from the Edit menu, or select nodes and press the Delete key. Select nodes and choose Cut from the Edit menu, or select nodes and press Ctrl+X. Select nodes and choose Copy from the Edit menu, or select nodes and press Ctrl+C. Choose Paste from the Edit menu, or press Ctrl+V. Creating and manipulating nodes The basic building block of shader creation is called a shader node or graph node. It is an instance of what is called a shader class or graph node class. A graph node can be an individual unit or a group of nodes that have been packaged into a Phenomenon or material definition. Shader nodes have a yellow title bar, Phenomena a blue title bar and material definition can be recognized by their green title bar. A Phenomenon be treated as a single node that can be incorprated in other shader graphs. Material definitions on the other hand are containers that describe fundamental shader characteristics in one single node. While a material definition does not have an output attachment, the node manipulations work the same as with the other node units. The current section describes how to create and manipulate individual node units. See page 32 for information about how to create and manipulate the inner workings of Phenomena. Nodes can be created and manipulated in several ways, including the following, which are described in more detail below: Rename a node The name of a node appears in its title bar. To rename a node: 20 mental mill User Guide, doc Copyright c 2010 mental images

27 Introduction to mental mill Standard Edition Creating and manipulating nodes 1. Right-click in the title bar of the (closed) node. 2. Choose Rename <node name> in the context menu which pops up. 3. Edit the name in the dialog which pops up. Open/close parameters Each node lists input parameters on its left and output parameters on its right. An input parameter can be opened only if it is an array or structure. An output parameter can be: Opened, in which case its contents are displayed above its name, or Closed, in which case its contents are hidden. If an input or output parameter is an array or structure, a list of its array elements or structure members is shown when it is open. Array elements and structure members may themselves be arrays or structures. Indentation is used to reflect the depth of an element in a hierarchy of structures or arrays. Nested arrays and structures can be opened successively until individual elements are revealed. To open a closed parameter or to close an open parameter left-click on the parameter name in the node. There is an alternative way to open and close parameters that are arrays or structures. A closed array or structure parameter has a + to its left which can be left-clicked to expose a list of its elements or members, and an open structure or array parameter has a - to its left which can be left-clicked to hide the list. Hide input and output parameters of nodes To hide input parameters, hold down the shift key and drag the bottom side of the node up. You can adjust the visibility of input parameters by moving the splitter bar. See callout 1 in the following figure. To hide output parameters, hold down the shift key and drag the top side of the node down. The following illustration shows an example of node parameter scrolling: Copyright c 2010 mental images mental mill User Guide, doc

28 Introduction to mental mill Standard Edition Creating and manipulating nodes In the preceding illustration, note the following: Callout 2a and 2b: When some, but not all, parameters are visible, a scroll bar is displayed. Callout 3a and 3b: You can scroll using the scroll bar or by dragging visible parameters. When all input or output parameters are hidden, only the parameter bar is visible. Wires connected to hidden parameters are semi-transparent as shown in the following illustration: 22 mental mill User Guide, doc Copyright c 2010 mental images

29 Introduction to mental mill Standard Edition Creating and manipulating nodes Add/remove state parameters A state parameter provides access to current information about the state of the renderer and the intersection that led to the shader call. To add a state parameter: 1. Right-click in the input parameter area of the node, or the context menu of the title bar, to bring up a context menu. 2. Choose the Add state parameter sub-menu. 3. Choose the state parameter to add as input from the list of state parameters which appears. To remove a state parameter: 1. Right-click on the state parameter name in the node. 2. Choose the Remove <state parameter name> option from the context menu which pops up. State input parameters will override the corresponding state value for the shader to which it has been added. For example, adding a normal input to a Phong node will allow the value of the normal to be controlled by the input. This input can be attached to the output another node, such as a make normal node. State parameters can be edited like other input parameters, as described on page 25. Select nodes Node selection is used for grouping nodes together in Phenomenon creation, for node editing, for exporting shader code, and for node deletion, cutting, and copying. To select an individual node, left-click on the node. To select multiple nodes: 1. Left-click in an empty space of the graph view. 2. Drag the mouse to create a rectangular region in which to select nodes. 3. Release the left mouse button to select all nodes which overlap the chosen rectangular region. Node selection can be toggled with node deselection by holding down the Ctrl key. Each time the left mouse button is clicked or released from a click and drag, the mode toggles from selection to deselection or from deselection to selection. To select all nodes, choose Select All from the Edit menu, or press Ctrl+A. Move nodes To move a node or group of nodes: Copyright c 2010 mental images mental mill User Guide, doc

30 Introduction to mental mill Standard Edition Creating and manipulating nodes 1. Select the nodes to be moved. 2. Left-click on the title bar of any of the selected nodes. 3. Drag the node(s) to the desired location. 4. Release the left mouse button. Resize nodes and output previews To resize a node, which also has the effect of selecting it: 1. Left-click the border of the node. You can select any side or corner. 2. Drag the border to create the desired size. 3. Release the left mouse button. Note: All visible input and output parameters remain visible. To resize previews of output parameters: 1. Move the mouse pointer over the border of an output preview. 2. Left-click and drag the mouse to resize the output preview. 3. Release the mouse button. Notes: A preview must be open before you can resize it. To display the preview of an output parameter, click to the left of the output parameter name. If your node has multiple output parameters, you can resize each preview individually. Delete a node or group of nodes To remove a node or group of nodes: 1. Select the nodes to be removed. 2. Choose Delete from the Edit menu, or press the Delete key. Cut, copy, or paste nodes To remove a node or group of nodes and add them to the clipboard: 1. Select the nodes to be cut. 24 mental mill User Guide, doc Copyright c 2010 mental images

31 Introduction to mental mill Standard Edition Editing input parameters 2. Choose Cut from the Edit menu, or press Ctrl+X. To add a node or group of nodes to the clipboard without removing them from the graph view: 1. Select the nodes to be copied. 2. Choose Copy from the Edit menu, or press Ctrl+C. To paste whatever nodes are contained on the clipboard into the graph view, choose Paste from the Edit menu, or press Ctrl+V. Editing input parameters If an input parameter is attached to an output parameter of another node, that output parameter determines its value, and the input parameter cannot be edited. To edit unattached input parameters right-click on the parameter name in the node and choose Edit <parameter name> from the context menu which pops up or use the parameter editor. The parameter editor provides a visual, intuitive way to alter input values. If the parameter editing space is not visible along the right-hand side of the application window, use the Parameter Editor toggle in the View menu, or press Ctrl+E, to display it. When a single node is selected in the graph view, then its input parameters and input parameter values are displayed and can be edited in the parameter editing space. If more than one node is selected, then only the parameters which are common to all selected nodes, based on parameter name, are displayed. If the value of a common parameter is the same in all selected nodes, then that value is shown in the parameter editor. Otherwise, the parameter editor leaves the value blank, and the user interface controls for the parameter are put into an indeterminate state. When a value for that parameter is entered in the parameter editor, that value is applied in all selected nodes, and the indeterminate state is lifted. Types of input parameters and the parameter editor capabilities which can be used to edit them include the following, which are described in more detail below: Input type Boolean Enumeration Integer Float Vector Color Texture Array or structure Appearance in parameter editor Checkbox Drop-down menu Slider Slider Group of sliders or checkboxes Color picker and component sliders File name editor and file browser None (Use the context menu) Boolean In the parameter editor, Booleans are displayed as checkboxes, as shown below. When a box is checked, the boolean is set to a value of true. Otherwise, the value is set to false. Copyright c 2010 mental images mental mill User Guide, doc

32 Introduction to mental mill Standard Edition Editing input parameters Another way to edit a boolean parameter is to right-click on it in the node and select Edit <boolean parameter name> from the context menu which pops up. A dialog then appears in which a false or true value can be chosen. Enumeration In the parameter editor, enumerations are displayed as a drop-down selector from which values may be chosen, as shown below. Another way to edit an enumeration parameter is to right-click on it in the node, select Edit <enumeration parameter name> from the context menu which pops up, and choose the desired value. Integer and float In the parameter editor, integers and floats are displayed as sliders with the value displayed in a box to the right of the slider, as shown below. Edit the value using the parameter editor in one of the following ways: Left-click on the slider itself to set a value, or Left-click on the arrows at either end of the slider to move the value, or Type a value in the box beside the slider and press Enter The range shown on the slider can be changed for some parameters. In those cases, left-clicking on an arrow at either end of the slider dynamically adapts the range when extremes are reached, and rightclicking on the slider brings up a context menu with several range options. In particular, Set <value> as the minimum limit for <integer or float> readjusts the slider scale so that the current value is the minimum value of the slider. Set <value> as the maximum limit for <integer or float> readjusts the slider scale so that the current value is the maximum value of the slider. Shrink slider range lessens the overall slider range and Grow slider range expands it. Another way to edit an integer or float parameter is to right-click on the parameter in the node and select Edit <integer or float parameter name> from the context menu which pops up. A dialog then appears in which a value can be entered. Vector 26 mental mill User Guide, doc Copyright c 2010 mental images

33 Introduction to mental mill Standard Edition Editing input parameters In addition to vectors with floating point components, the mental mill application supports vectors with integer or boolean components. In the parameter editor, vectors with integer or floating point components are displayed as collections of sliders with one slider per component, as shown below. The sliders can be used the same way as they are for integers and floats, as described above on page 26. Vectors with boolean components have one checkboxes per component. boolean is set to a value of true. Otherwise, the value is set to false. When a box is checked, the Another way to edit a vector is to right-click on the parameter in the node and select Edit <vector parameter name> from the context menu which pops up. A dialog then appears in which a value for each component can be entered. Color In the parameter editor, color parameters are displayed as square color swatches which are blended with a checker pattern based on alpha value. The parameter editor supports a built-in modeless color picker control. Left-click on the color swatch to open the editing environment. In the editing environment, the current color is shown on the lower right. The figure below shows an open editing environment for a diffuse color input parameter and a closed color swatch for a specular color input parameter. The editing environment is compact, but it contains a lot of information, so if some parts of it are not visible, resize the parameter editing space by left-clicking and dragging on the inner (left) edge of it. Edit the value using the parameter editor in one of the following ways: Pick a color using the 2D gradient swatch and 1D gradient column, or Use the set of four component sliders, or Type in a value and press the Enter key in each box beside the sliders The first way to use the parameter editor to choose a color is to use the color picker. On the left, the editing environment contains a 2D gradient swatch, called the primary color display, with a 1D gradient column to its right. These can be used to adjust color interactively. Two kinds of color spaces are supported in the gradient swatches, namely Hue/Saturation/Lightness (HSL) and Red/Green/Blue (RGB). For each of Copyright c 2010 mental images mental mill User Guide, doc

34 Introduction to mental mill Standard Edition Editing input parameters these, two components are represented in the 2D gradient swatch and the third component is represented in the 1D gradient column. The default is HSL with saturation and lightness depicted in the 2D gradient swatch. To choose the two components represented in the 2D gradient swatch, use the drop-down menu labeled Primary color display in the lower middle of the editing environment. If an HSL color space is chosen, then below the drop-down menu for the primary color display a checkbox offers the option of Dynamic Hue/Saturation. When checked, the color swatches update dynamically as the color is changed. The default is for this box to be unchecked. The other ways to use the parameter editor are to use sliders or boxes. Above the drop-down menu for the primary color display is a set of four sliders, one each for hue, saturation, lightness, and alpha, or one each for red, green, blue, and alpha, depending on the type of color space chosen for the primary color display. In particular, the opposite color space is displayed with the slider controls as for the primary color display, so if the swatches display HSL, then the sliders display RGB and vice versa. The sliders and boxes beside them can be used the same way as they are for integers and floats, as described above on page 26. There are also two ways to edit color parameters without using the parameter editor. Right-click on the parameter name in the node to bring up a context menu and then choose one of the two options in the Edit <color parameter name> sub-menu. The Color picker option brings up a window which contains a visual way to choose the desired color. Hue, saturation, lightness, red, green and blue values can also be edited directly in the color picker window. A button in the color picker called Add to Custom Colors is provided to save colors for future use. The color picker limits the color components to a range between 0 and 1. The other option for editing color values without using the parameter editor is the Value type-in option. It brings up a window in which red, green, blue and alpha can be edited as unconstrained values. Texture In the parameter editor, texture parameters are displayed as the file name of the texture, as shown below. Edit the file name and press Enter, or left-click on the button labeled... to the right to open a window to search for the desired texture file. Another way to edit texture values is to right-click on the parameter in the node and choose Edit <texture parameter name> from the context menu which pops up. A window then appears in which a texture file can be chosen. Array and structure If an parameter is of type struct or array the parameter appears collapsed in the parameter editor: 28 mental mill User Guide, doc Copyright c 2010 mental images

35 Introduction to mental mill Standard Edition Editing input parameters The view can simply be expanded by clicking the header bar of the struct or array: Dynamic arrays allow the user to choose the size of the array: Click the Size button on the header bar of the node and type in a number for the array size. Arrays with a fixed size and structs do not offer a size button. However, parameters can be nested. This means that it is possible to have an array of structs, for example: Copyright c 2010 mental images mental mill User Guide, doc

36 Introduction to mental mill Standard Edition Editing input parameters The nodes on the workspace also indicate when parameters are part of a struct or an array. The + sign indicates that a parameter can be opened / collapsed which is useful when another node is to be connected to one of the nested input parameters. Parameter states The Parameter Editor provides commands to control the state of each parameter. A parameter can have one of the following three states: Enabled: Set to a literal value. The default state of most parameters is enabled. The parameter value is editable by the user using the controls provided by the Parameter Editor, setting it to a literal value. Connected: Attached to the output of another node. A parameter is in the connected state when it has an attachment to the result of another node. So instead of reading a literal value, it will receive the result of the node ((or Phenomenon input interface) that it is connected to. Connecting nodes is the most fundamental principle of mental mill, so you will always have many parameters that are in the connected state. Inherited (Disabled): Inherits the default values from the class. Inherited (disabled) parameters don t read their values from the node instance. Instead they inherit their value from the shader class default. When a parameter is in this state, its value is not editable in the Parameter Editor. Instead the parameter value is copied from the value specified by the shader class (e.g., a parameter initializer in the MetaSL source code). Inherited parameters are particularly useful when the shader class initializes the value with a non-const expression. For example, texture lookup nodes assign texture coordinates from the shader state to initialize the texture coordinate input parameter (which defaults to the inherited state). Changing Parameter States Users can set the parameter states directly in the parameter editor of mental mill. By right-clicking the parameter in the parameter editor different action can be performed, depending of the current state of the parameter. The following actions are possible: Enable parameter PARAMETER NAME: When a parameter is disabled, this option will enable it. Depending on whether the parameter is or is not connected to another node, it switches to the connected state or enabled state. 30 mental mill User Guide, doc Copyright c 2010 mental images

37 Introduction to mental mill Standard Edition Manipulating Phenomena The following illustration shows the color state enabled: Attach parameter PARAMETER NAME to: This allows the user to attach this parameter to the result of another node. mental mill lists all compatible outputs in the submenu. Using this command users can create attachments directly in the parameter editor rather than clicking and dragging in the graph view. The following illustration shows the color state connected: Disable parameter: Selecting this option from the contextual menu will put the parameter in the inherited mode. Graph view navigation There is no limit to how much space a shader graph can occupy. The graph view can be enlarged or moved to view any part of a graph. To pan the view, left-click and drag with the middle mouse button in a part of the graph view not covered by a preview render. To zoom the view, either left-click and drag with the right mouse button or use the mouse scroll wheel in a part of the graph view not covered by a preview render. The Layout graph option in the View menu arranges all nodes in the visible part of the graph view in an orderly manner. The Frame selection and Frame all options, also found in the View menu, zoom the graph view so that all selected nodes or all nodes, respectively, fit in the visible part of the graph view. Here is a summary of these actions: Graph view navigation action Pan Zoom Zoom to view all nodes Zoom to view selected nodes Organize all nodes Access Middle-click and drag Right-click and drag, or use the scroll wheel Choose Frame all in the View menu, or press the A key Choose Frame selection in the View menu, or press the F key Choose Layout graph in the View menu, or press Ctrl+L Copyright c 2010 mental images mental mill User Guide, doc

38 Introduction to mental mill Standard Edition Manipulating Phenomena Manipulating Phenomena A Phenomenon is a set of cooperating shaders with a set of requirements. From the outside, a Phenomenon looks like a regular individual node. On the inside, it packages together shaders and rendering options which work together to create a complex effect. Packaging an effect in this way is optional and can be useful for reusing it or for organizing portions of a large shader graph. Phenomena can be created and manipulated in the following ways, described in more detail below: GUI element Description 1. Node name Label displaying the name of the node 2. input parameter / interface parameter Interface parameters can be adjusted via the parameter slot editor. They are connected to the nodes inside the Phenomenon to provide control over the network inside. 3. Top bar Used for moving the node. Offers special right-click context menu 4. open/close button Opens or closes the node so that the graph inside will become visible. 5. maximize / unmaximize button Same as open/close, but opens the node to its maximum extents. 6. preview window Shows a navigatable preview of the Phenomenon output parameter. 7. Output interface connection Attachment point where the nodes from inside the Phenomenon connect to the output which is visible from outside the Phenomenon. Rename a Phenomenon class Use the context menu (right-click) in the title bar of the Phenomenon 8. Output parameter Output parameters can be connected to other nodes outside the Phenomenon. 9. bottom bar Used for moving the node. Offers special right-click context menu Other actions that can be performed with Phenomena: 32 mental mill User Guide, doc Copyright c 2010 mental images

39 Introduction to mental mill Standard Edition Manipulating Phenomena Phenomenon action Rename a Phenomenon class Clone a Phenomenon class Other Phenomenon manipulations Edit an open Phenomenon Add/Remove Phenomenon parameters Rename parameters of a Phenomenon Access Use the context menu (right-click) in the title bar of the Phenomenon Use the context menu (right-click) in the title bar of the Phenomenon To rename, select, move, resize, delete, cut, copy, or paste Phenomenon nodes, or to open or close Phenomenon node parameters, or to add or remove state parameters to or from a Phenomenon node, use the same node actions as are described starting on page 20 Use regular graph view shader building tools Use the context menu (right-click) on the name of a parameter in a node contained in the Phenomenon Double click on the name of the Phenomenon parameter or right-click and choose Rename Parameter Name Create a Phenomenon See page 17 for creating a Phenomenon. Rename a Phenomenon class To rename the Phenomenon class to which a Phenomenon node belongs: 1. Right-click on the title bar of the Phenomenon node. 2. Choose Rename node class <Phenomenon class name> from the context menu which pops up. 3. Edit the Phenomenon class name. Clone a Phenomenon class Cloning Phenomenon class allows it to be altered and instantiated while maintaining the original class. To clone a Phenomenon class to which a Phenomenon node belongs: 1. Right-click on the title bar of the Phenomenon node. 2. Choose Clone node class <Phenomenon class name> from the context menu which pops up. This both creates a class identical to the one in which a Phenomenon node belongs and creates an instance of this newly created class in the graph view. Other Phenomenon manipulations A Phenomenon node can be manipulated just like any individual node (see page 20). It can be renamed, selected, moved, resized, deleted, cut, copied, or pasted. Also, parameters of a closed Phenomenon can be opened and closed, and state parameters can be added or removed. Copyright c 2010 mental images mental mill User Guide, doc

40 Introduction to mental mill Standard Edition Manipulating Phenomena Edit a Phenomenon The input parameters of a closed Phenomenon can be edited just like those of any other node. See page 25 for more information. An open Phenomenon shows the inner workings of the Phenomenon and is a virtual 2D graph space which can be navigated in the same manner as the main graph view, as described on page 31. Nodes can be created, edited and attached inside a Phenomenon just as they are in the main graph view. When a Phenomenon is maximized, the graph view shown is treated as the current graph view, and nodes contained in it that are not part of a Phenomenon in the view are considered top-level nodes. Phenomena can be created inside of other Phenomena. The depth of Phenomenon nesting is unlimited. A Phenomenon belonging to a nested set of Phenomena can also be maximized. It covers any maximized Phenomenon already in place. When unmaximized, the underlying Phenomenon is again shown. A nested Phenomenon is shown in the following figure: Select/Deselect multiple parameters These actions is most useful when you are working with Phenomena and need to select or unselect multiple parameters, for example: From a node, selecting the input parameters that you want to add to a Phenomenon s interface You select a node inside a Phenomenon and then select the input parameters of that node that you want to add to the Phenomenon s interface. From a node, adding multiple outputs inside a Phenomenon to the Phenomenon s output interface 34 mental mill User Guide, doc Copyright c 2010 mental images

41 Introduction to mental mill Standard Edition Manipulating Phenomena Reordering interface parameters of the Phenomenon Do one of the following : Hold down the Ctrl key and click the parameters that you want to select. Depending on its previous selection state the parameter will be toggled selected or unselected. Right click a parameter label and from the context menu choose Select all parameters or Deselect all parameters. Add/Remove Phenomenon parameters Unlike nodes found in the mental mill shader library, Phenomena do not have built-in input and output parameters. Adding input and output parameters to a Phenomenon provides a way to attach the shader graph contained in it to nodes outside the Phenomenon. You can add input and output parameters to the Phenomenon by selecting input parameter and output parameters of nodes contained in the Phenomenon or by creating new input and output Phenomenon parameters To add an input or output parameter to a Phenomenon: 1. From an open Phenomenon, select an input or output parameter from a node contained in the Phenomenon: (a) Right-click on the name of the parameter in its node. The context menu is displayed. (b) Choose Add <parameter name> to <Phenomenon name>. Note: You cannot mix input and output parameters. An input parameter of a node can be added as an Phenomenon input parameter only. The same applies for output parameters. 2. From a closed Phenomenon, create a new input or output Phenomenon parameter: (a) Select one of the following: New input parameter New output parameter The Rename Parameter dialog is displayed. (b) Edit the Display name and Internal name input fields and click OK to add the Phenomenon parameter. To remove a Phenomenon s input or output parameter: 1. Right-click on the name of the Phenomenon parameter in the closed or open Phenomenon node. 2. Choose Remove <parameter name> from the context menu which pops up. Just as in closed nodes, input parameters of an open Phenomenon are shown on its left and output parameters on its right. The figure above shows an open Phenomenon in which four input parameters and one output parameter are defined. Copyright c 2010 mental images mental mill User Guide, doc

42 Introduction to mental mill Standard Edition Attaching sub-shaders Rename parameters of a Phenomenon Note: You can rename the parameters of Phenomenon only. When you add a parameter to the interface of a Phenomenon, it uses the display name of the node from which it was exposed. If this name is not appropriate to the new context, you should change it. To rename a Phenomenon s input or output parameter: 1. There are two methods of renaming an interface parameter: (a) Double click the interface parameter that you want to rename. (b) Right-click on the name of the Phenomenon and choose the Rename <parameter name> option from the context menu which pops up. 2. Edit the internal and/or display name for the parameter. Display Name is the name displayed in the mental mill GUI. Internal Name is the name used in the code representation and is used for example, when the shader is exported. Reordering interface parameters Phenomena and material definitions usually have multiple interface parameters that are connected to parameters of the network inside. Extending and modifying a Phenomenon or material definition can make it necessary to rearrange its interface parameters so that they appear in a different order. 1. In a Phenomenon or material definition, select the parameters that you want to reorder (holding down the Ctrl key and clicking the parameters) 2. Left click and drag the parameters to the desired position. A dark black bar indicates at which position the parameters will be inserted. 3. Release the mouse. The selected parameters will be moved to the given position. Creating a parameter group for a Phenomenon or material definition 1. Ctrl-click the input parameters of the node to select or unselect them. It does not matter whether the node is open or closed. 2. When you have selected all parameters that go into one group, right-click in the input parameter section and choose Group selected parameters. A dialog box is displayed. 3. Specify a name for the group and click OK. The group is created and is displayed in the Parameter Editor as a group that can be folded and unfolded like struct or array parameters. 36 mental mill User Guide, doc Copyright c 2010 mental images

43 Introduction to mental mill Standard Edition Exporting the shader Attaching sub-shaders Lights, volume, and environment shaders are called sub-shaders. Their attachment to the surface shader is specified in the Render Scene Settings dialog. A generated shader can be made up of a collection of independent shader graphs: one for the surface, one for light or one for each light in the light list, one for environment, and one for volume. For example, instead of attaching an Environment map cubic shader to the shader graph to add reflections, Component reflection should be used while at the same time specifying the environment shader in the Render Scene Settings dialog. Sub-shaders play a role when exporting shaders. When compiling for hardware, any sub-shaders used by the graph being exported must be linked to the shader. Specification of other sub-shaders is optional. In most cases, the sub-shaders are combined at the time of export. The exception is when exporting with interfaces to CgFX, in which case sub-shaders need not be specified, and the surface, volume, environment, and light shaders are exported individually by defining Cg interfaces. To set sub-shaders, first create node instances of the lights, environment shader, and volume shader desired in the graph view. Then use the Render Scene Settings dialog, which is accessible in the Render menu, to attach the sub-shaders. The Light List box in the dialog shows the lights currently attached to the shader. To add lights, click on the Add light... button. Volume and environment shaders can be chosen by using the drop-down menus in the dialog. Note that the Selected Light Parameters in the Render Scene Settings dialog, including the coordinate system used and light position, direction, spread, and distance limit, affect the node render preview windows, but are not part of the shader exporting mechanism. See page 54 for more detailed information about the Render Scene Settings dialog. Exporting the shader Exporting the shader allows a selected graph or Phenomenon to be written out as shader code for a target platform. Keep in mind the following when exporting shader graphs: Export requirements: Only one node may be selected for export. The selected node must be a top-level node. All necessary sub-shaders must be attached. Precisely one node must be chosen when exporting. It should be the root of the shader graph of interest, in other words the node whose shader output is the final output of the shader graph to be exported. The node selected when exporting must be a top-level node. In other words, only nodes that are not part of any Phenomenon in the current graph view space may be selected for export. To export a node that is contained in a Phenomenon, first maximize the Phenomenon and then select the node. If the shader is to be exported to hardware (except for exporting to CgFX with interfaces) and the shader uses lights, environment, or volume sub-shaders, then these must be attached before exporting. For instance, if the shader contains a light loop, then a light instance must appear in the graph view and be attached as a sub-shader in the render scene settings. See page 54 for more information about how to set render scene settings. Copyright c 2010 mental images mental mill User Guide, doc

44 Introduction to mental mill Standard Edition Exporting the shader The export command supports the formats which are described below. The command in the File menu called Export... allows a selected graph or Phenomenon to be exported as shader code for a target platform. When it is chosen, the Export options dialog appears. A drop-down menu presents all available export formats, which are described below. There are two types of export: those which provide simple, hands-off exporting to specific applications and those which supply advanced users custom control. The custom options expose several compiler options that may help the user, for instance a game developer, to avoid having to write an exporter. The exported shader code contains a copyright notice, which can include an optional portion provided by the user. To specify a copyright notice, put the desired text in a file named "user copyright.txt" somewhere in the shader path. If present, the text in this file will be inserted into the exported shader code. FX Composer TM The FX Composer export option supports the use of CgFX and HLSL FX shaders in the FX Composer integrated development environment for shader authoring. The FX Composer export option in mental mill provides checkboxes in the Export options dialog to choose CgFX, HLSL FX, or both as the formats to export. A file name must also be given. All of the appropriate compiler options are set automatically. The CgFX and/or HLSL FX files that are written are specialized for use with FX Composer. Autodesk 3ds Max legacy (HLSL) and Autodesk 3ds Max 2010 Use the DirectX Shader workflow to load a.xsml file for rendering in the viewport and by mental ray. There is no need to export the file from mental mill. Autodesk 3ds Max 2011(slate extension) Windows only Unlike the other exporter dialogs, which ask for a file name, this dialog asks you to specify the directory that contains the 3ds Max executable (3dsmax.exe). The exporter encapsulates the selected node as a Phenomenon (.xmsl file). The Phenomenon is written to the <3dsmax>\mentalimages\shaders standard\metasl\xmsl\ directory. The exporter will not overwrite any write-protected files or any standard files shipped with the original 3ds Max file installation. The exporter loops through any shader sources (.msl files) that the exported node is dependent on. Any files that are needed that are not included in the standard set of.msl files shipped with 3ds Max, and are not write protected, are copied to the <3dsmax>\images\shaders standard\metasl\msl\ directory. To see the exported shader, you must start or restart 3ds Max, whichever is appropriate. The shader is displayed as a new entry in the 3ds Max Slate Material Editor under Maps > MetaSL. Maps > MetaSL is only visible when you use MetaSL-compatible renderers such as mental ray or Quicksilver. Notes: Windows Vista and Windows 7: If the "User Access Control" feature is enabled, it is likely the export will fail. The exporter will issue a warning message. 3dx Max configuration files: The exporter modifies two 3ds Max configuration files to add the shader to the Slate material editor under Maps > MetaSL. These files are located in the <3dsmax>\mentalimages\shaders standard\metasl\config\ directory and are named MaxMetaSLNodeTexmap.tbx and NodeToMSL MappingTable.xml. The first time the exporter 38 mental mill User Guide, doc Copyright c 2010 mental images

45 Introduction to mental mill Standard Edition Exporting the shader modifies these configuration files, it creates backup copies with a.bak extension so you can always revert to the original files if necessary. Name of saved shader and shader values: The shader is saved under the name you assigned it originally, not the class name. Any values you set in the node in mental mill are the default values used in 3ds Max. Material shaders: If you want to use a material shader (.xmsl file), use the DirectX option to load the material shader. The export option is for Phenomena only. CATIA The CATIA export option supports the use of CgFX shaders in the CATIA software suite. The CATIA export option in mental mill requires only that a file name is given in the Export options dialog. All of the appropriate compiler options are set automatically. The CgFX file that is written is specialized for use with CATIA. Maya The Maya export option supports the use of CgFX shaders in the Maya 3D modeling, animation, effects, and rendering solution. The Maya export option in mental mill requires only that a file name is given in the Export options dialog. All of the appropriate compiler options are set automatically. The CgFX file that is written is specialized for use with Maya. XSI The XSI export option supports the use of CgFX shaders in the XSI 3D graphics application. The XSI export option in mental mill requires only that a file name is given in the Export options dialog. All of the appropriate compiler options are set automatically. The CgFX file that is written is specialized for use with XSI. Custom CgFX The Custom CgFX export option provides export to the CgFX format with control over the compiler options used. The figure below shows the Export options dialog for this export option: Copyright c 2010 mental images mental mill User Guide, doc

46 Introduction to mental mill Standard Edition Exporting the shader A file name must be given, and several compiler options are available to be set. The first compiler option is to specify an annotation map file. Such files are XML-based files that specify annotations and semantics. An annotation map entry contains a list of FX annotations to generate for a given annotation in the shading language used in mental mill. A semantic annotation can be used to specify a semantic tag in the generated code. The default annotation map file name is default.axml. The Profiles section allows setting of vertex and fragment shader profiles, which the Cg compiler targets. The defaults are vp40 and fp40 for the vertex and fragment shader profiles, respectively. The Coordinate systems section allows the vertex coordinate space to be set to object, world, camera, or screen space through a drop-down menu. Similarly, the fragment coordinate space may be set to world or camera space. The coordinate system default for vertex coordinate space is object space, and the coordinate system default for internal space is camera space. The Normals sections contains two checkboxes that allow normals to be two-sided or to face forward. Two-sided normals support the state variable backside in the generated code. The shading normal will be flipped when the backside of a surface is rendered. If forward-facing normals are used, then normals facing away are flipped. The default is to use neither of these options. The Texturing section contains three checkboxes. The cube map can be rotated, in which case the y and z components of the cube map lookups in the generated code are switched. The default is not to rotate the cube map. 2D texture lookup can be flipped vertically, meaning that the v component of the 40 mental mill User Guide, doc Copyright c 2010 mental images

47 Introduction to mental mill Standard Edition Exporting the shader texture coordinate that is used to sample 2D textures is inverted. This can be used to compensate for the difference in origin of texture space between DirectX and OpenGL. The default is not to flip to 2D texture vertically. Filter and texture coordinate wrap states within sampler declarations can be generated. The default value is to generate sampler states. The Transparency section supports alpha transparency and order-independent transparency that can be turned on with checkboxes, but the default is to use neither. Alpha transparency assumes the surface shader has a transparency output. If the transparency output is a Color type, the average of the red, green, and blue components will be used to set the alpha component. Order-independent transparency adds an additional texture parameter to the shader (the depth texture) and inserts code to discard the current fragment depth if it is greater than or equal to the value in the depth texture. The Depth buffer section has depth test and depth write checkboxes, whose defaults are to be turned on. The depth test is performed to rejects fragments for shading, and the depth write sets the state so that the depth buffer is written to when surfaces are rendered. The Interfaces section contains compiler options to use interfaces and to evaluate the volume shader. Each is available as a checkbox. The default is unchecked for both. If interfaces are used, then the CgFX code generated uses interfaces to define connections to sub-shaders. If the volume shader is evaluated, then the CgFX code will include code to evaluate the volume sub-shader. Custom HLSL FX The Custom HLSL FX export option provides export to the HLSL FX format with control over the compiler options used. A file name must be given, and several compiler options are available to be set. The Custom CgFX and Custom HLSL FX exporters has several compiler options in common. See the Custom CgFX explanation above for more detailed descriptions of several of the shared compiler options. Like the Custom CgFX export format, the first compiler option for the Custom HLSL FX export format is to specify an annotation map file. The default annotation map file name is default.axml. The next section allows vertex and fragment shader profiles to be set. The defaults are vs 3 0 for the vertex shader profile and ps 3 0 for the fragment shader profile. The vertex coordinate space may be set to object, world, camera, or screen space through a drop-down menu. Similarly, the fragment coordinate space may be set to world or camera space. The coordinate system default for vertex coordinate space is object space, and the coordinate system default for internal space is camera space. A checkbox allows normals to face forward. The default is not to use forward-facing normals. There are three texturing compiler options in the form of checkboxes. As in the Custom CgFX exporter, these are to rotate the cube map, to flip 2D texture lookup vertically, and to generate sampler states. The defaults are not to perform the first two, but to generate sampler states. Alpha transparency and order-independent transparency can be turned on with checkboxes. The default is to use neither. The depth test and depth write checkboxes are turned on by default. The figure below shows the Export options dialog for this export option: Copyright c 2010 mental images mental mill User Guide, doc

48 Introduction to mental mill Standard Edition Exporting the shader Custom GLSL The Custom GLSL export option provides export to the GLSL format with control over the compiler options used. A file name must be given, and four other compiler options are available to be set. The GLSL version number is defaulted to 110, but can be set. Three checkboxes allow for alpha transparency, order-independent transparency, and two sided normals. The default is to use none of these. See the Custom CgFX description above for more detailed information about alpha transparency, orderindependent transparency, and two-sided normals. The figure below shows the Export options dialog for this export option: 42 mental mill User Guide, doc Copyright c 2010 mental images

49 Creating material definitions Creating material definitions mental mill 1.1 introduces the concept of a material definition, which bundles fundamental shading characteristics of a shader into one single node, similar to a Phenomenon. Unlike a Phenomenon, a material definition has no outputs. It has predefined slots, called material components, which represent certain aspects of a material. Material components are: surface surface bsdf transparency ior displacement volume volume bsdf volume absorption volume scattering You can link a shader node or an entire shader branch to a material component for example surface or surface BSDF. 1 As you can imagine, material components are very useful. For example, when you export a material definition to different target rendering platforms it enables a variety of optimizations that would not be possible otherwise. There are a few basic rules that you must keep in mind when using material definitions: A BSDF shader must be connected to the surface bsdf component. The following BSDF shader models are delivered with mental mill: Ashikhmin Shirley Phong 1 MetaSL spec, 1.1.5: Material and light definitions Copyright c 2010 mental images mental mill User Guide, doc

50 Creating material definitions Creating a material definition Lambert Oren Nayar If a surface bsdf is defined, but no node is linked to the surface slot, then the integration uses the sum of the direct light and indirect light contribution based on the BSDF. Connections to other material component slots are optional. If no connections are defined, then the components are not evaluated or they exhibit a predefined default behavior. Creating a material definition The following sections describe two procedures to create material definitions: using material presets in the toolbox and using the context menu in the graph view. Creating a material definition from a Toolbox preset The mental mill toolbox contains presets for material definitions. definitions are already exposed to the interface. The parameters of these material To create a material definition from a toolbox preset: 1. Locate the material presets folder in the toolbox. 2. Drag and drop one of the material definition presets into the graph view. If you want to new material definition and store it in the toolbox, rename the node class: 1. In the graph view, right-click the top bar of the material definition. The context menu is displayed. 2. From the context menu choose Rename Node class <class name>. A dialog box is displayed. 3. Type a new name and click OK. Creating a material definition from the graph view To create a material definition from the graph view: 1. Right-click on an empty space in the graph view and select Create Material from the popup menu. A dialog box is displayed. 2. Type in a name for your material definition, choose an appropriate BSDF, then click OK. The material definition is displayed in the opened state and the BSDF is already connected to the surface bsdf material component. The following illustration shows a material definition using a Phong BSDF shader: 44 mental mill User Guide, doc Copyright c 2010 mental images

51 Creating material definitions Extending a material definition Extending a material definition To extend the functionality of a material definition, you instantiate additional nodes and link them to the respective material component slots. For example, the surface bsdf material component is important for physically correct rendering and a physically-correct renderer might choose to evaluate this component to generate correct computational results. For special effects, you can extend the default behavior of the illumination model of the surface bsdf component. You do this by creating a subgraph that is linked to surface slot of the material definition. This is useful for example, in a feature film that requires an effect that go beyond the physically plausible behavior of the built-in surface BSDF. The following illustration shows a material with multiple subgraphs that are linked to the material components surface, surface bsdf, ior and transparency: Copyright c 2010 mental images mental mill User Guide, doc

52 Creating material definitions A note about the material component link Evaluating the BSDF in the surface subgraph In the surface branch it is possible to evaluate the surface bsdf and continue working on the result. mental mill provides two nodes that cover the most fundamental lookups and which are intended to be used in a surface subgraph: Surface components Surface direct indirect Use these shaders in a graph that is connected to the surface slot of a material definition. These shaders have multiple outputs that gather individual illumination subtypes from the surface bsdf graph. The results can be processed in an arbitrary way and subsequent results can be fed into a node that is linked to the surface slot of the material definition. A note about the material component link When you connect a node to a material component slot, a dotted line is displayed to indicate that the shader node is linked to that specific surface slot. The name of the node linked to the slot is automatically changed to the name of the material component slot. Why? Because the dotted link is theoretical only; it is the name of the last node of the subgraph that matters. 2 The node is automatically renamed by mental 2 See the MetaSL Spec 1.1.5, p.69: Material and Light Definitions 46 mental mill User Guide, doc Copyright c 2010 mental images

53 Output preview How to view individual output values mill when the link is created so that the logical link is established. The dotted line acts as a visual cue so that you always knows which part of the material definition the subgraph is driving. Undo and redo The mental mill application provides an undo/redo mechanism. Access it in the Edit menu or by using the shortcut Ctrl+Z for undo and the shortcut Ctrl+Y for redo. The number of undo steps kept is controllable. Access undo preferences in the Preferences option of the Edit menu. In the General tab of the Preferences dialog, if Infinite undo queue is checked all undo steps are kept. Otherwise, the number of steps shown in the Queue size box is kept. This number can be edited as desired. The default is to keep 50 steps. Undo preferences are stored in the user preferences file. See page 67 for more information about this file. Output preview If an output parameter is opened, its contents are pictured in a preview window above the parameter name. The preview window reflects the behavior of the node by showing its effect on an object. The preview includes alpha transparency. Transparency will be visible only if an output parameter named transparency is present on shader nodes or Phenomena. Several sample objects are available, including a sphere (which is the default object), plane, cube, torus, and terrain. Custom object types in the.obj Wavefront format are also supported. Set the custom object by using the Preferences dialog, which is accessible in the Edit menu. Choose the General tab and either type in the path and custom object file name or left-click on the... button to its right to search for a custom object. The following manipulations are available in the preview window: Preview window action Change object being viewed Rotate Pan Zoom Change light position View values Access Use the context menu (right-click) in the preview window Left-click and drag in the preview window Middle-click and drag in the preview window Right-click and drag or use the scroll wheel in the preview window Left-click and drag in the preview window while pressing Shift Left-click and drag on the object while pressing Ctrl When the light position is changed in one node, it is changed in all nodes simultaneously. The remainder of this section describes what information can be displayed for different output types, how to use the render scene settings, how to use animation to show how shader output varies over time, and how to set preview rendering preferences. Copyright c 2010 mental images mental mill User Guide, doc

54 Output preview How to view individual output values How to view individual output values To view individual values on the surface: 1. Pinpoint the desired location with crosshairs by left-clicking and dragging over the object while pressing Ctrl. 2. Read the value and other information for the chosen location in the yellow tooltip window that pops up. item Left-click on the button in the tooltip window to expand it and display additional information. The following subsections describe tooltip information for the following output types: Color on page 48 Booleans and Boolean vectors on page 49 int, float, and float2 on page 50 float3 and float4 on page 51 Matrix on page 52 Color output The figure below shows an example of an expanded tooltip window that displays results in a preview window. The tooltip window for Color results shows the following: 48 mental mill User Guide, doc Copyright c 2010 mental images

55 Output preview How to view individual output values Tooltip item r g b a luminosity range out of range Description Value of the red component Value of the green component Value of the blue component Value of the alpha component Weighted combination of components Range onto which each component is mapped over the surface Choice to clip component values out of range or highlight them Luminosity is the following weighted combination: luminosity = 0.3 * red * green * blue The default range is 0 to 1. If the colors are very dark, for instance if the variable represents a small delta to be added to another variable, then the range can be set to something smaller, such as [0.0, 0.1], to better visualize the values. The out of range option controls whether values outside of the specified range should be clamped or a highlight applied. The highlighting is useful for seeing which portions of the image are clipped. This works by testing each component individually, resulting in a boolean vector where true means it was clipped and false means it was within the range. This vector is then inverted so pixels are visible alongside nonclipped pixels and converted to a color. For example, if just the red channel is clipped, the resulting color values are 0 for red, 1 for green, and 1 for blue, i.e. cyan. Holding down Ctrl and dragging the mouse over the highlighted areas displays the precise (unclamped) values. Boolean and Boolean vector output The figure below shows an example of an expanded tooltip window that displays results in a preview window. The tooltip window for Boolean and Boolean vector results shows the following: Tooltip item value preview image Description False=0. True=1. Drop-down selector to choose whether the preview window displays the variable value mapped to a scalar/vector color (default) or the shader output The preview image selector has scaler/vector color and shader output options: Copyright c 2010 mental images mental mill User Guide, doc

56 Output preview How to view individual output values Scaler/vector color option: A color representation of the scalar or vector is displayed in the preview window. A value of 0 (false) or 1 (true) is mapped to a color. For example, a bool4 vector (true, true, false, false) maps to yellow (1, 1, 0, 0). Shader output option: The preview image displays the shader output. Shader output mode allows visual features only visible in the output image to be referenced to locate a particular surface position of interest. int, float, and float2 output The figure below shows an example of an expanded tooltip window that displays results in a preview window. The tooltip window for int, float, and float2 results shows the following: Tooltip item value (int and float only) x (float2 only) y (float2 only) preview image range out of range Description Value of the integer or float Value of the x component Value of the y component Drop-down selector to choose whether the preview window displays the shader output or the variable value mapped to a scalar/vector color Range onto which each component is mapped over the surface Choice to clip component values out of range or highlight them The preview image selector has scaler/vector color and shader output options: Scaler/vector color option: A color representation of the scalar or vector is displayed in the preview window. To control the mapping from a scalar or vector to a color: Integers, floats, and the corresponding vector types provide the following range choices: Two range entry fields: For a float or int vector, the x, y, z, and w components are mapped to the red, green, blue and alpha components of the color. If there is no z or w component, or both, they are set to 0 and 1, respectively. Values inside 0 and 1 are mapped to the specified range. For mapping scalars to colors, the process is similar: The value of the scalar is mapped to the red component of the color 50 mental mill User Guide, doc Copyright c 2010 mental images

57 Output preview How to view individual output values The green and blue components are set to 0 The alpha component is set to 1 The result is mapped to the specified range. Exception: If the red component lies outside the interval 0 to 1, it is clamped or highlighted (uses the out of range choice). Out of range radio buttons: clamp: Values outside the range are clipped highlight: Values outside the range are highlighted Shader output option: A color representation of the result of the overall shader is displayed in the preview window. For example: If the selected output value is a debug variable, the color representation displayed in the preview window represents the overall shader including the debug variable. However, the numerical information displayed in the tooltip corresponds to the values of the variable. It enables you to match up numerical values of the variable with specific locations of the shader output. If the selected output value is the result parameter, the color representation displayed in the preview window is identical to the representation displayed when selecting scalar/vector color or determinant. float3 and float4 output The figure below shows an expanded tooltip window for a vector result in a preview window. When the tooltip is displayed, an arrow object is also drawn in the preview window to visualize the vector. When the mouse is moved with Ctrl held down, the arrow object is updated to reflect the value under the cursor location. The arrow is a shaded 3D object, tapered at the base so the precise location from which it originates can be seen. When the mouse button is released, the arrow remains in its last position, allowing the view to be rotated, panned and zoomed to get a better sense for the position and direction of the arrow. For example, when visualizing the direction state variable, the arrow always points away from the camera. The view can be manipulated after releasing the Ctrl key to get a better feel for the direction at that particular surface location. The tooltip window for float3 and float4 results shows the following: Copyright c 2010 mental images mental mill User Guide, doc

58 Output preview How to view individual output values Tooltip item x y z w (float4 only) length preview image range out of range source space vector type vector size Description Value of the x component Value of the y component Value of the z component Value of the w component Length of the vector Drop-down selector to choose whether the preview window displays the shader output or the variable value mapped to a scalar/vector color Range onto which each component is mapped over the surface Choice to clip component values out of range or highlight them Drop-down selector to choose the coordinate system in which the vector value is located Drop-down selector to choose whether the arrow displayed represents a direction vector or is interpreted as a vector from the surface position to the vector value Slider to control an appropriate size of the arrow for different viewpoints The preview image selector works the same as for int, float, and float 2 (see page 50). The source space selector allows for object, world, camera or raster coordinates to be used for the vector value. The arrow displayed in the preview window is transformed from the coordinate space specified. The vector type selector allows for the vector to be interpreted either as a directional vector or as a positional vector that begins at the surface position and ends at the vector value. The vector size slider controls how large a vector of a given length appears on the screen. It can be used to adjust arrow size for different viewpoints. Matrix output The figure below shows an example of an expanded tooltip window for a matrix shader variable in the preview window. In the preview itself, a tripod of arrows is drawn to represent the upper-left 3x3 of the matrix. For a 4x4 matrix, the fourth row or column usually represents translation, but this translation is not used to translate the location of the arrow tripod; the tripod is always located at the position of the fragment being 52 mental mill User Guide, doc Copyright c 2010 mental images

59 Output preview How to set preview rendering preferences debugged. The arrows are colored so that the x-axis of the coordinate system represented by the matrix is drawn in green, the y-axis in red, and the z-axis in blue. The tooltip window for matrix shader variables shows the following: Tooltip item Description 3x3 grid of values Values of upper-left 3x3 of the matrix preview image Drop-down selector to choose whether the preview window displays the shader output (default) or the variable value mapped to a matrix determinant. draw axis 3x3 or 4x4 matrices only. Drop-down selector which determines if the displayed arrow tripod is based on the rows or the columns of the matrix. source space 3x3 or 4x4 matrices only. Drop-down selector to choose the coordinate system in which the vector value is located. axis size 3x3 or 4x4 matrices only. Slider to an appropriate size for the arrow tripod for different viewpoints. The preview image option works the same way as for int, float, and float 2 (see page 50). A tripod of vectors is supported for 3x3 and 4x4 matrices only. The matrix determinant option represents the mathematical determinant. For square matrices (2x2, 3x3, 4x4), a color representation of the determinant is displayed in the preview window, where: The red component shows the value of the determinant The blue and green components are set to 0 The alpha component is set to 1 For non-square matrices (2x3, 2x4, 3x2, 3x4, 4x2, 4x3), a color representation of the determinant is displayed in the preview window, where: The [0][0] element shows the value of the determinant The red, blue, and green components are set to the value of the [0][0] component The color presentation is a grayscale shading The alpha component is set to 1 If the matrix is not invertible at a particular surface location, then the determinant will be zero and displayed as black. The source space option also works the same way as for float3 and float4 output (see page 52). The axis size slider works for the arrow tripod like the vector size does for float3 and float4 output (see page 52). Copyright c 2010 mental images mental mill User Guide, doc

60 Output preview Render scene settings How to set preview rendering preferences Settings for preview rendering are accessible in the Preferences... option of the Edit menu. In the Preview Rendering tab there are sections for gamma correction and for shader handling. The gamma correction section contains a checkbox to enable gamma correction, and a box in which the gamma value can be typed if gamma correction is selected. The shader handling section gives a choice to use the CgFX back-end, the GLSL back-end, or no back-end for preview rendering. The Apply button gives the opportunity to verify that the new preview rendering preferences are the ones desired before closing the Preferences dialog. If no back-end is used for preview rendering, a simple default shading is used in the preview windows. This mode may be useful when running mental mill on a computer that does not have adequate capabilities to handle hardware rendering. If CgFX or GLSL preview rendering is chosen and a hardware compilation error occurs, it is indicated in the preview window by a red wireframe in place of a shaded object. If hardware rendering cannot handle the shader, it may revert to software rendering, leading possibly to significant performance issues that cause preview renders to be produced too slowly to be interactive. When hardware rendering falls back to software, it is indicated in the preview window by a blue wireframe in place of a shaded object. Render scene settings The Render Scene Settings dialog, accessible from the Render menu, is shown below. It plays a role when exporting shaders (see page 37) and provides options to control the way node previews are rendered. It allows a volume shader, an environment shader, and a list of light instances, each of which is attached to a light shader, to be attached to the surface shader. It also allows attributes of light instances, such as position and direction, to be modified in the node render preview windows. The dialog contains the following controls: Light List The light list contains an entry for each light instance. The name that appears in the list is the name of the light shader assigned to the light instance. One or more items can be selected in the list. 54 mental mill User Guide, doc Copyright c 2010 mental images

61 Output preview Render scene settings Selected Light Parameters This section contains the parameters for the lights selected in the light list. Unlike the other settings in the Render Scene Settings dialog, this section affects node render preview windows only; it does not affect shader exports. When multiple lights are selected, the parameter values for all selected lights are displayed. If the values of a particular parameter differ among selected lights, the individual controls display an indeterminate state. For example, a checkbox is neither checked nor unchecked, but instead is filled with a solid color. When the value of a light parameter is changed that change is applied to each selected light. If the parameter value was previously not common among selected parameters, it will be after it has been modified. Most of the light instance parameters displayed in the Selected Light Parameters section provide values for light state variables. The parameters in this section are: Parameter On Light Type Coordinate System Position Direction Spread Distance Limit Light Shader Choose... Description If not checked, selected lights are disabled Drop-down selector to choose point, spot, infinite or planar light types (corresponds to the state variable light type) Specifies world space in which lights remain fixed regardless of camera position or camera space in which lights are headlights, effectively attached to the camera position (useful for shader editing since lights almost always illuminate the area in view of the camera) Position of selected lights (corresponds to the state variable light position) Direction of selected lights (corresponds to the state variable light direction) Spread value for selected lights (corresponds to the state variables light spread and light spread cos which are typically only used by spot lights to determine the size of the light cone) Distance limit value (corresponds to the state variable light distance limit) Light shader currently assigned to selected lights Brings up a dialog that allows a new light shader to be selected The position for each light can be modified interactively with the mouse for the purpose of previewing the effects of lighting. Click and drag while pressing the Shift key on a preview window to modify the position of selected lights. Add Light... Selecting this button displays another dialog which allows a light shader to be selected from the light shaders in the graph view. A new light instance will be created and added to the list which uses the selected light shader. Multiple light instances can be created from any light shader. Remove Light Clicking this button will remove selected lights from the list. Ambient Color Clicking this button brings up a color picker to choose a scene-constant color which can be used to simulate global illumination. mental mill uses illumination nodes without an ambient component in order Copyright c 2010 mental images mental mill User Guide, doc

62 Output preview Render preview to support physically correct material libraries. When defining a larger number of materials, say a hundred, using ambient is attractive. However, setting an ambient value for each material easily leads to inconsistent values. To solve this issue, mental mill provides a built-in ambient light, accessible through this button in the Render Scene Settings dialog. To create a direct ambient parameter in mental mill for an illumination node, attach its sum output to one of the input parameters of a Math color add node, and use the other input parameter of the Math color add node as the ambient parameter. Volume Shader and Environment Shader Below the light section, two drop down lists allow the volume and environment shaders to be selected from shaders in the graph view. Selecting [default] from these lists causes no shader to be used in the volume shader case and a cube mapped reflection to be used in the environment shader case. Load..., Save, and Save as... The Render Scene Settings dialog of the Render menu provides a way to save the options specified in it as a scene file which is an XML-based file with standard extension.xml. The scene file is independent of the mental mill.xmsl project file. See page 61 for more information about saving and using project files. Current scene and Close The Current scene box lists the file name of the current scene settings. The Close button can be clicked to exit the Render Scene Settings dialog. Render preview mental mill includes a mental ray preview plug-in to enable you to view the differences between rendering on the CPU/GPU and in software. To access this plug-in, use the External renderer options dialog shown in the following illustration. The dialog contains the following fields and buttons: 56 mental mill User Guide, doc Copyright c 2010 mental images

63 Output preview Animation External Renderer: mental ray is the default external renderer. renderer to the drop-down list. Currently, you cannot add another Image resolution: Width and height of the image in pixels. The default is 512 x 512, but you can render an image as large as 1024 x Image quality: Moving the slider to the left increases the image quality by reducing aliasing. You will need to experiment to find the best balance between image quality and rendering speed for a particular image. Cancel: Cancel the preview rendering operation. The dialog is closed. Any changes to the Image quality slider are saved. OK: Render an image, which is displayed in a dialog box. The image resolution and image quality settings are saved. To preview render in mental ray, perform the following steps: 1. In the graph view, select the shader you want to render. 2. From the main menu, select Render > Render preview.... The External renderer options dialog is displayed. 3. Check that mental ray is selected as the external renderer. If not, select it from the drop-down list. 4. Change the image resolution and image quality to suit your needs. 5. Click OK to start the preview render operation. Your scene is rendered and displayed in a dialog box. Notes: A node in the graph view must be selected for rendering. If no node is selected, an error message is displayed and the render operation is ended. Not all shaders can be rendered in mental ray. In such cases, an error message is displayed and the render operation is ended. If the node that you render requires a light or an environment shader but none is specified, an error message is displayed and the render operation is ended. In this case, you need to specify a light or environment shader as specified in the following procedure: 1. From the main menu, select Render > Scene Settings.... The Render Scene Settings dialog is displayed. If you need to add a light, perform step 2. If you need to assign an environment shader, perform step If the light list is empty, select Add light and create a light from the list of light shaders. Note: If the light list is empty, no light shader was added to the graph view. In this case, add a light shader to the graph view. Then you can create a light. 3. Check that an environment shader is selected from the Environment shader drop-down list. Note: If the selection list is empty, no environment shader was added to the graph view. In this case, add an environment shader to the graph view. Then you can assign an environment shader. 4. Close the Render Scene Settings dialog. Copyright c 2010 mental images mental mill User Guide, doc

64 Debugging shaders Animation Animation is especially helpful for visualizing shader graph results that are time dependent. Preview windows can be viewed as a function of time by turning on the Animate toggle in the View menu. A small running clock in the lower left of the application window indicates the current time in the animation. Select Reset animation in the View menu to set the clock back to zero. There is also a stepping mechanism available when the Animate toggle is turned off. Choose Step animation forward or Step animation backward in the View menu to move time forward or backward, respectively. Here is a summary of these options: View menu option Shortcut Description Animate Up arrow key Toggles animation on and off Step animation forward Right arrow key Moves the time forwards if animation is off Step animation backward Left arrow key Moves the time backwards if animation is off Reset animation Down arrow key Sets the animation clock to zero Debugging shaders Each node instance has two small, square-shaped buttons in its upper right corner. These control whether the node is open or closed and maximized or not, as described for Phenomenon nodes on page 20. When a Phenomenon node is opened, its internal shader graph is exposed. A node which is not a Phenomenon is called a Metanode TM. When a Metanode is opened, the MetaSL code which implements it and the graphical debugger are displayed, as shown below. There are four main components of an open Metanode: the code view, input parameters, output parameters, and shader variables in scope. The main part of the window contains the code view. The code view can be panned and scaled using the mouse. A context menu in the code view, described in the next section, gives access to several debugging options. 58 mental mill User Guide, doc Copyright c 2010 mental images

65 Debugging shaders Code view Input parameters, output parameters and shader variables in scope are displayed on the left and right of the opened Metanode, and these can be sized by clicking and dragging on the dark gray sizer bars located on the inner side of the parameter areas. To scroll through the shader variables, left-click and drag on the sizer bar with the Shift key held down. Parameter editing for input parameters and preview windows for output parameters and shader variables are described on page 60. Code view The main window of an open Metanode shows its code contents. Some Metanodes, notably math operations, are intrinsically generated and therefore have no code view available. In most nodes the code is available. In the code view, lines of MetaSL code have a white background. The active line of MetaSL code, which can be selected by left-clicking on the desired line of code, is highlighted in light green. The selected line can be thought of as a breakpoint, the point within the code where the values of variables are displayed. Lines which are not MetaSL code cannot be selected and are shown with a light gray background. Right-clicking on the code area displays a context menu with the following options: Edit <file name> Use this menu option to edit the MetaSL source file. The text editor displayed is either the built-in text editor or a specified external text editor. The Preferences dialog, which can be accessed in the Edit menu, allows external editors to be selected and configured. See page 61 for more information. Reload <file name> Reloading forces the MetaSL source file to be reloaded to apply changes made externally. The Editor tab of the Preferences dialog, which can be accessed in the Edit menu, provides an option to automatically reload the source file when it changes. Debug options... When the selected MetaSL statement highlighted in green is inside one or more loops, the line may be executed zero or more times. The Debug options dialog controls the number of iterations executed at the breakpoint. A value of 1 means that the breakpoint will be activated the first time the selected line is reached. The number keys 1 through 0, with 0 treated as 10, serve as hot keys to set the loop iterations, making it easier to step through loops. A common use for the loop iteration control is when iterating over lights in a for each statement. Consecutively increasing loop iterations allows the effect of each light to be inspected in the debugger. It is possible that the breakpoint specified by the selected line will not be reached because the selected line is in the body of a conditional statement, such as an if statement, or because the selected line is in a loop which terminates before the selected number of loop iterations is reached. The Debug options dialog controls what should happen in this case in terms of visualization over the surface. There are two options: show output and discard fragment. When show output is selected, the final output of the shader is rendered instead of the debug variable. When discard fragment is selected, rendering of the current fragment is aborted, which effectively results in a hole in the surface at the fragment location. Copyright c 2010 mental images mental mill User Guide, doc

66 Debugging shaders Editor preferences Debug variable filters The Debug variable filters... menu item brings up the dialog shown below. The variables in scope at the selected line are displayed on the right side of an open Metanode. However, because there are many state variables available to shaders in addition to the shader s own local variables, the list can be quite long. The debug variable filters dialog allows variables to be hidden from the list to make it easier to focus on the variables that are the most relevant. By default, all shader variables are shown and all state variables, except those explicitly referenced by the shader, are hidden. The debug variable filters dialog has two sections separated by an adjustable splitter. The top section contains a list of state variables and the bottom section contains a list of local variables. When a variable is selected in the list it will be hidden in the Metanode variable list. Both sections have buttons to automatically select all variables, no variables, or to invert the current selection. Parameters Just as in a closed node, an open Metanode shows input parameters on the left and regular parameter editing of them is available. See page 25 for more information about how to edit input parameters. Output parameters are listed on the right at the top of an open Metanode. Preview windows are available for output parameters, just as they are in a closed node. Left-clicking on the output parameter name toggles the preview window on or off. See page 47 for more information about previewing output. Shader variables in the scope at the selected line of MetaSL code are listed on the right of an open Metanode below the output parameters. Left-click and drag on the sizer bar with the Shift key held down to scroll through the shader variables. Just as output parameters have preview windows, so do shader variables. See page 47 for more information about previewing output. Information about viewing colors, scalars (floats), vectors, and matrices can be found there. 60 mental mill User Guide, doc Copyright c 2010 mental images