Gather Loop VEX node

Sends rays into the scene and contains a subnetwork of VOPs to operate on the information gathered from the shaders of surfaces hit by the rays.

All Parameters Inputs Outputs

See also: For Loop, While

Overview

The Gather VOP sends rays into the scene (the number of rays is controlled by the samples input). You specify the information you want from the hit surfaces by adding inputs to the gather node (see below). The gather node contains a subnetwork (double-click the node to go inside). You can wire up VOPs in the subnet to operate on the input values, for example to sum up the colors (Cf attributes) of the hit surfaces.

The gather VOP acts like a loop. The subnet inside is run for every sample. You can connect additional inputs to specify the values to import from the hit surfaces or to use as variables in the loop (for example, as an accumulator for a value imported from each hit surface).

Adding inputs and importing values from hit surfaces

Adding inputs and importing values to the Gather VOP is slightly unintuitive.

  1. To simply add an input variable to the gather node, wire a VOP (such as a Constant VOP) into the next input on the gather VOP to add the input.

    Add inputs representing variables you intend to import from surface shaders before any other inputs.

    Tip

    The gather VOP uses the output label of the incoming wire to label its inputs. So, to give the inputs meaningful names, in the Constant VOP’s parameters, set the Constant name parameter.

    For example, if you are connecting a Constant VOP to create an input that you will use to import Cf, in the Constant VOP’s parameters, set Constant name to something like Cf_import.

  2. Use the Number of imports parameter in the gather VOPs parameter interface to set the number of inputs that represent imports from the hit surfaces.

    For example, if you connect 5 additional inputs, and set Number of inputs to 3, the first three added inputs would represent imports, and the last two would be non-imported variables.

  3. For each of the imported variables, in the gather VOP’s parameter interface, set the corresponding text box (e.g. Import 0, Import 1, etc.) to the name of the variable you want to import from the hit surface.

    This can be the name of an attribute on the surface, or the name of an exported parameter of the surface shader. You can also use the special variable names ray:origin, ray:direction, and ray:length to import information about the ray itself.

    The menu button to the right of the text box lets you quickly select from a list of common imports:

    Surface color (Cf)

    The Cf (diffuse color) of the hit surface.

    Surface opacity (Of)

    The Of (opacity) of the hit surface.

    Ray origin (ray:origin)

    The actual origin of the ray.

    Ray direction (ray:direction)

    The actual direction of the ray (with the cone).

    Ray length (ray:length)

    The length of the ray to the hit surface.

Subnetwork and outputs

Double-click the gather VOP to go to the subnetwork inside. This subnetwork is run for every ray hit.

  • The subinput node provides the values from the gather VOP’s inputs.

  • Connect VOPs to the suboutput node to make them available as outputs of the gather VOP.

Example

To add up the colors of all hit surfaces:

  1. Create two Constant VOPs. In the parameter editor, set the Constant type of both nodes to “Color”.

  2. Connect the two Constant nodes as additional inputs to the gather VOP (wire them into the gather VOP’s next input).

  3. In the parameters of the first Constant node, set Constant name to Cf_import. In the parameters of the second Constant node, set Constant name to sum.

  4. In the gather VOP’s parameters, set the Number of imports to 1 and set Import 0 to Cf.

  5. Double-click the gather VOP node to go into its subnetwork.

  6. Create an Add VOP.

  7. Connect the _Cf_import and _sum of the subinput node into the Add.

  8. Connect the Add node’s sum output into the suboutput node’s _sum connector.

  9. Press U or click in the path control at the top of the network editor to go back up.

    The gather node now has a _sum output.

Parameters

Number of imports

The number of additional inputs (that is, inputs you add by connecting VOPs to the next input) that get their value by importing variables from the hit surfaces.

For example, if you connect 5 additional inputs, and set Number of inputs to 3, the first three added inputs would represent imports, and the last two would be non-imported variables.

Inputs

The gather loop has two sets of inputs, a fixed set and a variadic set. The fixed inputs are:

P

The ray origin. Default is the global P.

dir

The ray direction (this should be normalized). Default is the global N variable.

angle

The cone angle to sample. Default is 0.

samples

The number of samples (rays) to send. Default is 1.

bias

The ray-bias. Default is 0.05.

maxdist

The maximum distance each ray can travel before giving up. A value of -1 means no maximum distance. Default is -1.

Outputs

Outputs appear on the gather VOP for connected inputs to the suboutput node in gather node’s subnetwork.

Usages in other examples

Example name Example for