Houdini 11 VEX VEX functions

Variadic Gather Arguments

There are three types of arguments you can pass to the gather loop: arguments controlling how to send rays, what information to pass to the shaders of other surfaces hit by the ray, and what information to import back from each sent ray.

Controlling how to send the rays

These argument pairs control how the gather statement sends rays into the scene.

KeywordValue typeDescriptionDefault
samples int/floatNumber of rays to send. (Gather only)1

The distribution angle (specified in radians). Rays will be distributed over this angle. (Gather only)

distribution string

Determines the sampling distribution. For Gather,

  • cosine – Rays are distributed by the cosine (diffuse) function over the hemisphere.

  • uniform – Rays are distributed uniformly over the hemisphere

For sample_geometry,

  • area – Samples are distributed by primitive area

  • parametric – Samples are distributed by primitive ID, subdivision ID, and parametric surface coordinates (s, t).

  • solidangle – Samples are distributed either by primitive area or by primitive area and solid angle subtended by the primitive.

biasfloat Ray-tracing bias.0.001

Sample identifier to be passed to the called shader. If the calling shader has used SID to generate samples, it can be useful to pass the modified sample identifier to the called shader so that it can begin sampling at the specified offset. This value will be used to initialize the SID global in the hit surface.


A hint to mantra to indicate the relative contribution of this ray to the final shading. This value is used by the ray clip threshold to limit sending of rays (similar to ray bounce).


The type of rays you are sending. Mantra will use raystyle to determine both the default raytracing mask and bounce limit used for ray termination.

  • reflect – Sending reflection rays. Mantra will use the reflection mask and reflection limit to terminate raytracing.

  • refract – (default) Sending refraction rays. Mantra will use the refraction mask and refraction limit to terminate raytracing.

  • diffuse – Sending diffuse rays. Mantra will use the diffuse limit for diffuse rays.

  • shadow – Sending shadow rays. Mantra will not modify the raytracing level and will trace against shadowmask if inside a shadow or light shader.

  • nolimit – Sending reflection rays with no limit on the number of raytracing bounces. Mantra will still increment the raytracing level when sending nolimit rays.

scopestring A list of objects which can be hit by the rays. When specified, scope overrides the default scope that would have been selected for the given raystyle. The "scope:default" value will cause the scope argument to use the default scope for the current context - as if the argument were not specified.

The maximum distance to search for objects. This can be used to limit the search of objects to nearby objects only. If the maxdist given is negative, then it will act as if there is no maximum distance.


Typically, rays are distributed over the surface of the micro-polygon being shaded. This argument can be used to control the area. A value of 0 will force all rays to be sent from the same point. A value of 1 will cover the entire micro-polygon. (Gather only)


The name of a VEX export variable to use for variance anti-aliasing. The renderer compares the value with adjacent micropolygons in micropolygon rendering to decide what shading points need additional samples (using vm_variance property as a threshold). If more samples are required, the algorithm takes samples up to the specified maximum ray samples.

This variable must be imported from the hit surface, so it must be in the list of imported names (see “importing information back from the ray” below). If the named variable is not imported, this option will be ignored.

Variance antialiasing puts more samples in areas of the image with high variance, for example a sharp shadow edge. It is only used when vm_dorayvariance is enabled. Otherwise, only the min ray samples (or an explicitly supplied "samples" value) are used for antialiasing of the gather loop.

See also the Pipeline option section in the gather function help.

Sending information to the hit surface's shader

Using a keyword in the form "send:name", value, you can pass data from the originating surface to surfaces which are intersected by the ray. These arguments pass any values you want.

gather(P, dir, "send:N", normalize(N)) { ... }

You can extract this passed data on the receiving end (that is, in the surface being hit by the ray) with the rayimport function. The first argument is the name (without the send: prefix) and the second argument is a variable in which to store the imported value.

int rayimport(string name, type &value)

rayimport returns 1 if the value was imported successfully.

Importing information back from the ray

You can specify names of global or exported variables to import from the hit shader in the form "varname", &var, typically including Cf (color vector of surface hit) and Of (opacity vector of surface hit).

vector  hitcf;
gather(P, dir, "bias", 0.01, "Cf", hitcf) {...}

In addition, you can import the following special keywords to get information about the ray itself:

KeywordValue typeDescription
ray:originvector The origin of the ray (defined in else clause also).
ray:directionvector The direction of the ray (defined in else clause also).
ray:lengthfloatThe distance to the first surface which was hit by the ray.
ray:areafloatThe total surface area of all the geometry in the raytracing scope.
ray:solidanglefloatThe estimated solid angle subtended by all geometry in the raytracing scope. For large objects close to or enclosing the ray origin, this may be a very poor estimate while for individual primitives the estimate can be very good.

By default, Houdini composites the global variables using opacity blending. In some cases, it’s more useful to get the value from the closest surface (regardless of whether it’s transparent). You can use the special samplefilter keyword with a string value of either closest or opacity to control whether the value of a global is from the closest surface or opacity blended.

When the samplefilter keyword is encountered in the argument list, all following import variables will use the specified filtering mode. You can specify multiple samplefilter arguments in a single gather statement to filter different variables in different ways.

gather(P, dir,
        "samplefilter", "opacity",
            "Cf", hitCf,
            "Of", hitOf,
        "samplefilter", "closest",
            "P", hitP,
            "N", hitN)

Pipeline option

As you specify variables, you can intersperse pipeline keyword options to control where in the pipeline to fill out read/write variables. The value can be one of surface, atmosphere, or displacement. You can specify the pipeline option multiple times. Each use of the option affects any variables specified after it (up to the next usage of pipeline if any).

gather(p, d, "pipeline", "surface", "Cf", surfCf,
             "pipeline", "atmosphere" "Cf", fogCf, "P", hitP)

Light mask


You can use the lightmask keyword argument to pass a light name pattern to limit the set of lights used to illuminate the hit surface. This allows the tracing surface to control the lighting of the hit surface. The "scope:default" value will cause the lightmask argument to use the default light mask for the current context - as if the argument were not specified.

    ..., "lightmask", "hotlights*");

On this page

Related topics