[Port] [6000.0] DOCG-7709 Clarify Shader Graph Sub Graph topic around use cases

Author: markg-unity

Packages/com.unity.shadergraph/Documentation~/Add-Inputs-Outputs-Sub-Graph.md

@@ -0,0 +1,44 @@
+# Add inputs and outputs to a Sub Graph
+
+To pass data in and out of a [Sub Graph](Sub-graph.md), create input and output ports.
+
+## Create an input port
+
+To create an input port, add a property to the blackboard of the Sub Graph. Follow these steps:
+
+1. Open the Sub Graph asset.
+2. In the Blackboard, click the **+** button and select the type of property you want to add.
+3. Drag the property from the Blackboard into the graph area to create a Property Node.
+
+When you add the Sub Graph to a shader graph, the property appears as an input port on the Sub Graph Node.
+
+## Create an output port
+
+To create an output port, add a port to the **Output** Node of the Sub Graph. Follow these steps:
+
+1. Open the Sub Graph asset.
+1. Select the **Output** node.
+1. In the **Graph Inspector** window, select the **Node Settings** tab.
+1. Under **Inputs**, select the Add (**+**) button.
+1. Use the dropdown to select the output type.
+
+When you add the Sub Graph to a shader graph, the property appears as an output port on the Sub Graph node.
+
+## Avoid preview errors
+
+The Preview window uses the first output port to generate the preview image. To avoid an error, ensure the first output port is one of the following data types:
+
+- `Boolean`
+- `Float`
+- `Vector 2` 
+- `Vector 3`
+- `Vector 4`
+- `Matrix 2`
+- `Matrix 3`
+- `Matrix 4`
+
+For more information, refer to [Custom Port Menu](Custom-Port-Menu.md).
+
+## Additional resources
+
+- [Branch On Input Connection node](Branch-On-Input-Connection-Node.md)

Packages/com.unity.shadergraph/Documentation~/Add-Sub-Graph-To-Shader-Graph.md

@@ -0,0 +1,20 @@
+# Add a Sub Graph to a shader graph
+
+To add a [Sub Graph](Sub-graph.md) to a shader graph, use one of the following approaches:
+
+- Drag the Sub Graph asset from the Project window into the Shader Graph window.
+- In the Shader Graph window, right-click to open the context menu, then select **Create Node** > **Sub Graph** and the name of your Sub Graph.
+
+Unity adds a Sub Graph node to the shader graph. For more information, refer to [Sub Graph Node](Sub-graph-Node.md).
+
+## Change the location in the Create Node menu
+
+To change the location of the Sub Graph in the **Create Node** menu, follow these steps:
+
+1. Open the Sub Graph asset.
+2. In the blackboard, select the gray **Sub Graphs** label.
+3. Type the name of another folder from the **Create Node** menu, for example **Artistic**.
+
+## Additional resources
+
+- [Sub Graph node](Sub-graph-Node.md)

Packages/com.unity.shadergraph/Documentation~/Branch-On-Input-Connection-Node.md

@@ -1,57 +1,16 @@
 # Branch On Input Connection node
 
-The Branch On Input Connection node allows you to change the behavior of a Subgraph based on the connected state of an input property in the parent Shader Graph. You should use the Branch On Input Connection node when you want to create a default input for a port
+The Branch On Input Connection node allows you to change the behavior of a [Sub Graph](Sub-graphs.md) based on the connected state of an input property in the parent shader graph. Use the Branch On Input Connection node to create a default input for a port.
 
-Shader Graph determines whether the property in the parent Shader Graph is connected, or not connected, and chooses a value to use as an output based on that connection state.
+For more information, refer to [Set default inputs for a Sub Graph](Sub-Graph-Default-Property-Values.md).
 
-![An image of the Graph window, that shows the Branch on Input Connection node.](images/sg-branch-on-input-connection-node.png)
-
-Shader Graph uses two ports when it determines the node's connection state:
-
-- The Branch On Input Connection node's **Input** port.
-
-- The Subgraph node's matching Property port in the parent Shader Graph. For more information on Subgraph nodes, see [Subgraph node](Sub-graph-Node.md).
-
-The Branch On Input Connection node's functionality is based on the [Branch node](Branch-Node.md).
-
-> [!NOTE]
-> You can't use the Branch On Input Connection node with a Streaming Virtual Texture Property. For more information on Streaming Virtual Texturing, see [Using Streaming Virtual Texturing in Shader Graph](https://docs.unity3d.com/Documentation/Manual/svt-use-in-shader-graph.html).
-
-The Branch On Input Connection node generates branching HLSL source code, but during compilation, the branch is optimized out of your shader.
-
-## Create Node menu category
-
-The Branch On Input Connection node is under the **Utility** > **Logic** category in the Create Node menu. You can only use it in a Shader Subgraph.
-
-To use the Branch On Input Connection node in a Subgraph:
-
-1. Open the Subgraph where you want to add a Branch On Input Connection node.
-
-2. In the Blackboard, do one of the following:
-
-    - To add a new property, select **Add** (+), then select a property type from the menu. Enter a name for your new property and press Enter. Then, select your property in the Blackboard and drag it onto your graph to create a Property node.
-
-    - Select an existing property in the Blackboard and drag it onto your graph to create a Property node.
-
-3. With your Property node selected, in the Graph Inspector, enable **Use Custom Binding**.
-
-    > [!NOTE]
-    > If you disable **Use Custom Binding**, you can't connect your Property node to the Branch On Input Connection node. If you've already made a connection, the Unity Editor breaks the connection and displays a warning on the node.
-
-4. In the **Label** field, enter the label for the default value that displays on your Subgraph node's port binding in its parent Shader Graph. For more information on port bindings, see [Port Bindings](Port-Bindings.md).
-
-5. Press Spacebar or right-click and select **Create Node**. Find the **Branch On Input Connection** node in the Create Node Menu, then double-click or press Enter with the node selected to add it to your Subgraph.
-
-6. On your Property node, select the output port and drag its new connection to the Branch On Connection node's **Input** port.
-
-7. To specify the value Shader Graph uses when the **Input** port is connected on the Subgraph node in the parent Shader Graph, connect a node to the **Connected** port. To specify the value that Shader Graph uses when the **Input** port isn't connected, connect another node to the **NotConnected** port.
-
-8. To specify how Shader Graph uses your **Connected** or **NotConnected** values in your shader, connect any valid node to the **Output** port on the Branch On Input Connection node.
+The node generates branching HLSL source code, but during compilation Unity optimizes the branch out of your shader.
 
 ## Compatibility
 
 The Branch On Input Connection [!include[nodes-compatibility-all](./snippets/nodes-compatibility-all.md)]    <!-- ALL PIPELINES INCLUDE  -->
 
+You can only use a Branch on Input Connection node in a [Sub Graph](Sub-graphs.md).
 
 ## Inputs
 
@@ -72,16 +31,6 @@ The Branch On Input Connection [!include[nodes-single-output](./snippets/nodes-s
 | :------  | :------- | :-------------  |
 | **Out**  | Dynamic Vector    | Outputs the value of either **Connected** or **NotConnected**, based on the **Input** property's connection state in the parent Shader Graph.        |
 
-## Example Subgraph usage
-
-In the following example, a Branch On Input Connection node specifies the default behavior for a UV Subgraph input property. When a value for the **UV** property is connected in the parent graph, then the value from that property is passed to the Checkerboard node to determine the UV coordinates for the checkerboard pattern. When the **UV** property isn't connected, then the Branch On Input Connection node uses the **UV0** channel from the UV node for the Checkerboard node's UV coordinates:
-
-> [!NOTE]
-> When you preview a Subgraph, the Branch On Input Connection node always uses its NotConnected value.
-
-![An image of the Graph window. A UV property is connected to the Input port on a Branch On Input Connection node. The property also connects to the Branch On Input Connection node's Connected input port, while a UV node with its channel set to UV0 connects to the NotConnected port. The Branch On Input Connection node's Out port connects to a Checkerboard node's UV input port.](images/sg-branch-on-input-connection-node-example.png)
-
-
 ## Related nodes
 
 <!-- OPTIONAL. Any nodes that may be related to this node in some way that's worth mentioning -->

Packages/com.unity.shadergraph/Documentation~/Change-Behaviour-Sub-Graph-Dropdown.md

@@ -0,0 +1,45 @@
+# Change the behavior of a Sub Graph with a dropdown
+
+To set up a [Sub Graph](Sub-graph.md) so you can change its behavior using a dropdown menu in shader graphs, use a **Dropdown** node. You can specify the number of options that appear in the dropdown menu, and their names.
+
+## Create a dropdown
+
+Follow these steps:
+
+1. From the **Project** window, open a Sub Graph asset.
+2. In the Blackboard, select **Add** (+), then select **Dropdown**.
+
+    **Note**: The **Dropdown** property appears only in the Blackboard for Sub Graphs, not regular shader graphs.
+
+3. Drag the new **Dropdown** property from the Blackboard to the Sub Graph. Unity creates a **Dropdown** node.
+
+When you add the Sub Graph to a shader graph, the **Sub Graph** node now has a dropdown menu with **A** and **B** options.
+
+## Customize the dropdown options
+
+To customize the options in the dropdown menu, follow these steps:
+
+1. In the Sub Graph, select the **Dropdown** property in the Blackboard window.
+2. In the **Graph Inspector** window, select the **Node Settings** tab.
+3. Next to **Entries**, select the **Add** (**+**) button to add a new option, or the **Remove** (**-**) button to remove an option. The minimum number of options is two.
+
+Each option you add adds a corresponding input port to the **Dropdown** node.
+
+## Set up the output for each option
+
+To set up the output for each option in the dropdown menu, follow these steps:
+
+1. Connect a node or set of nodes to each input port on the **Dropdown** node. Each input becomes active when the corresponding option is selected in the dropdown menu.
+2. Connect the **Out** port to the **Output** node.
+
+Each input port has the Dynamic Vector type, which allows you to connect any Vector type. For more information, refer to [Dynamic Data Types](Data-Types.md#dynamic-data-types).
+
+## Example
+
+In the following example, a Subgraph Dropdown node changes the UV channel it sends to the Subgraph's Output node. The selection on the Subgraph node in the parent graph changes whether the Subgraph outputs **UV1** or **UV0**. If the Subgraph is used in multiple Shader Graphs, the Subgraph Dropdown node can change the UV channel output without changing the Subgraph:
+
+![An image of the Graph window. The first input port on a Subgraph Dropdown node connects to a UV node and receives UV0. The second input port connects to a UV node and receives UV1. The Subgraph Dropdown node sends its output to the Subgraph's Output node.](images/sg-subgraph-dropdown-node-example-2.png)
+
+## Additional resources
+
+- [Sub Graphs](Sub-graph.md)

Packages/com.unity.shadergraph/Documentation~/Create-Sub-Graph.md

@@ -0,0 +1,24 @@
+# Create a Sub Graph
+
+To perform the same operations multiple times within a single shader graph or across multiple shader graphs, create a [Sub Graph](Sub-graph.md). 
+
+## Create a Sub Graph from existing nodes
+
+To create a [Sub Graph](Sub-graph.md) from an existing set of shader graph nodes, follow these steps:
+
+1. In the Shader Graph window, select the nodes you want to include in the Sub Graph.
+2. Right-click on one of the selected nodes to open the context menu.
+3. Select **Convert To Sub-graph**.
+
+Unity creates a Shader Graph asset in the Project window. To edit the Sub Graph, double-click the asset.
+
+**Note:** If a node in a Sub Graph specifies a [shader stage](Shader-Stage.md), the Sub Graph can only include nodes that work with or specify the same shader stage.
+
+## Create an empty Sub Graph
+
+To create an empty Sub Graph, in the Project window, right-click and select **Create** > **Shader** > **Sub Graph**.
+
+## Additional resources
+
+- [Change the behavior of a Sub Graph with a dropdown](Change-Behaviour-Sub-Graph-Dropdown.md)
+- [Custom Function Node](Custom-Function-Node.md)

Packages/com.unity.shadergraph/Documentation~/Node-Library.md

@@ -12,6 +12,7 @@ Explore nodes that enable color and channel manipulation, mathematical and proce
 | [Input](Input-Nodes.md)                                       | Learn about values, mesh attributes, gradients, matrices, deformation data, PBR parameters, scene information, and texture sampling options. |
 | [Math](Math-Nodes.md)                                         | Learn about mathematical operations.                                                 |
 | [Procedural](Procedural-Nodes.md)                             | Learn about creating patterns, noise textures, and geometric shapes.                                                                         |
+| [SpeedTree](SpeedTree8-SubGraphAssets.md)                     | Learn about using SpeedTree 8 Sub Graph assets |
 | [Utility](Utility-Nodes.md)                                   | Learn about basic preview, sub-graph referencing, and essential logic operations.    |
 | [UV](UV-Nodes.md)                                             | Learn about manipulation and mapping effects, enabling advanced texture animations, coordinate transformations, and warping techniques.      |
 

Packages/com.unity.shadergraph/Documentation~/Node.md

@@ -31,7 +31,7 @@ Right clicking on a **Node** will open a context menu. This menu contains many o
 | Paste | Pastes **Node(s)** in the clipboard |
 | Delete | Deletes selected **Node(s)** |
 | Duplicate | Duplicates selected **Node(s)** |
-| Convert To Sub-graph | Creates a new [Sub-graph Asset](Sub-graph-Asset.md) with the selected **Node(s)** included |
+| Convert To Sub-graph | Creates a new [Sub-graph](Sub-graph.md) with the selected **Node(s)** included |
 | Convert To Inline Node | Converts a [Property Node](Property-Types.md) into a regular node of the appropriate [Data Type](Data-Types.md) |
 | Convert To Property | Converts a **Node** into a new **Property** on the [Blackboard](Blackboard.md) of the appropriate [Property Type](Property-Types.md) |
 | Open Documentation | Opens a new web browser to the selected **Nodes** documentation page in the [Node Library](Node-Library.md) |

Packages/com.unity.shadergraph/Documentation~/SpeedTree8-SubGraphAssets.md

@@ -4,7 +4,6 @@
 This documentation assumes that you are already familiar with the concepts described in the following pages:
 * [SpeedTree](https://docs.unity3d.com/Manual/SpeedTree.html)
 * [Sub Graph Nodes](Sub-graph-Node.md)
-* [Sub Graph Assets](Sub-graph-Asset.md)
 * [Keywords](Keywords.md)
 
 The documentation on [ShaderLab material properties](https://docs.unity3d.com/Manual/SL-Properties.html) might also be contextually helpful.

Packages/com.unity.shadergraph/Documentation~/Sub-Graph-Default-Property-Values.md

@@ -0,0 +1,45 @@
+# Set default inputs for a Sub Graph
+
+To set the default inputs for a Sub Graph, use one of the following approaches:
+
+- For uniform defaults, for example a color or single coordinate, set the default value in the Graph Inspector window.
+- For varying defaults, for example a full set of texture coordinates, use a [Branch On Input Connection node](Branch-On-Input-Connection-Node.md).
+
+## Set uniform defaults
+
+After you [add an input to a Sub Graph](Create-Sub-Graph.md#set-inputs), follow these steps:
+
+1. In the Sub Graph, select the property in the Blackboard window.
+2. In the Graph Inspector window, select **Node Settings**, then set **Default Value**. 
+
+When you add the Sub Graph to a parent Shader Graph, the input port of the Sub Graph node uses the default value if the port isn't connected.
+
+## Set varying defaults
+
+> [!NOTE]
+> You can't use the Branch On Input Connection node with a Streaming Virtual Texture property. For more information, refer to [Using Streaming Virtual Texturing in Shader Graph](https://docs.unity3d.com/Documentation/Manual/svt-use-in-shader-graph.html).
+
+After you [add an input to a Sub Graph](Create-Sub-Graph.md#set-inputs), follow these steps:
+
+1. In the Sub Graph, select the property in the Blackboard window.
+2. In the Graph Inspector window, select **Node Settings**, then enable **Use Custom Binding**.
+3. Enter a name in the **Label** field. This label appears on the input in the parent shader graph.
+4. Right-click in the Sub Graph workspace to open the context menu, then select **Create Node** > **Utility** > **Logic** > **Branch On Input Connection** to add a [Branch On Input Connection node](Branch-On-Input-Connection-Node.md).
+5. Connect the property to the **Input** port of the Branch On Input Connection node. The node now outputs different values depending on whether the parent shader graph connects a node to the input.
+6. Connect the property to the **Connected** port. If the parent shader graph connects a node to the input, the Branch On Input Connection node uses that value. 
+7. Connect another node to the **NotConnected** port, for example a [UV node](UV-Node.md). If the parent Shader Graph doesn't connect a node to the input, the Branch On Input Connection node uses this as the default input.
+8. Connect the output of the Branch On Input Connection node to the rest of your sub graph.
+
+> [!NOTE]
+> The preview in the Branch On Input Connection node always uses the **NotConnected** value.
+
+## Example
+
+The following sub graph inputs the default UV0 coordinates of the mesh if the parent Shader Graph doesn't connect a node to the input.
+
+![A Vector2 property connected to the Input and Connected inputs of a Branch On Input Connnection node. A UV node is connected to the NotConnected input. The Use Custom Binding property of the Vector2 property is enabled. The Branch On Input Connection node outputs to an Output node.](images/shader_graph_branch_on_connection.png)
+
+## Additional resources
+
+- [Branch node](Branch-Node.md)
+- [Sub Graphs](Sub-graphs.md)