| float4x4 get_transform( String from, String to) |
Get a transformation matrix to transform from one space to another
including user-defined coordinate systems. The from and
to parameters can be the name of a user-defined coordinate
system or "internal", "object", "world", "camera", "light", or "raster".
The matrix returned from get_transform() assumes that vectors are considered to be column vectors and multiplied on the right hand side of the matrix. In other words, the translation components of the matrix, Tx, Ty, and Tz, would be located in the following positions of a matrix that contained only translation:
1 0 0 Tx 0 1 0 Ty 0 0 1 Tz 0 0 0 1 |
| float3 transform_point( String from, String to, float3 pt) |
Transform a point from one coordinate system to another. The from and to parameters can be the name of a user-defined coordinate system or "internal", "object", "world", "camera", "light", or "raster". |
| float3 transform_vector( String from, String to, float3 v) |
Transform a vector from one coordinate system to another. The translation component of the coordinate systems is ignored when transforming the vector. The from and to parameters can be the name of a user-defined coordinate system or "internal", "object", "world", "camera", "light", or "raster". |
| float3 transform_normal( String from, String to, float3 n) |
Transform a normal from one coordinate system to another. As with vector transformations, the translation component of the coordinate systems is ignored. Additionally the transpose of the inverse transformation matrix is used. The from and to parameters can be the name of a user-defined coordinate system or "internal", "object", "world", "camera", "light", or "raster". |
| Spectrum sample_spectrum(Spectrum s) | Returns a sampled spectrum with values defined by evaluating s at the wavelengths given in the wavelength_sample state variable and zero elsewhere. |
| Spectrum sample_spectrum( int index, float value) |
Returns a sampled spectrum with the value at wavelength wavelength_sample[index] set to value and zero elsewhere. The value of index must be greater than or equal to zero and less than wavelength_sample.count. |
| Spectrum sample_spectrum(float values[]) | Returns a sampled spectrum with values at wavelengths wavelength_sample set to values and zero elsewhere. The value of values.count must be equal to wavelength_sample.count. |
| void spectrum_choose_index( inout double primary_sample, out int index, out float probability) |
Selects a wavelength by index in the wavelength_sample array based on the primary_sample $\in U([0,1))$ and writes the value to the index argument. The value of primary_sample is rescaled to $U([0,1))$ after the selection so that it can be used for another sampling operation. The probability of selecting index is written to the probability argument. |
| float eval_at_index( Spectrum s, int index) |
Evaluates and returns the value of s at the wavelength wavelength-_sample[index]. The value of index must be greater than or equal to zero and less than wavelength_sample.count. |
| bool is_ray_dispersal_group(String group) | Returns true if the current ray is a member of the given group. This parameter must be a literal string. |
| bool is_ray_history_group(String history) | Returns true if the current ray is a member of the given history group. This parameter must be a literal string. |
| bool trace( Ray ray, Trace_options options, parameter_selector: result, ...) bool trace( Ray ray, Ray ray_dx, Ray ray_dy, Trace_options options, parameter_selector: result, ...) bool trace( Ray ray, Trace_options options, String parameter_selector, out T result, ...) bool trace( Ray ray, Ray ray_dx, Ray ray_dy, Trace_options options, String parameter_selector, out T result, ...) |
Trace the given ray. This function returns false if nothing was
hit or the trace depth was exhausted. If a hit is encountered
one or more output values are stored in the given result variables.
Calling an environment shader is defined as a hit. Environment
shaders can be enabled or disabled with the Trace_options parameter.
Two versions of this function exist, one without and one with ray differentials. Without ray differentials, the renderer makes a best effort based on the ray type to provide ray differentials. In the version with ray differentials the user can compute and provide the ray differentials including setting them to zero if that is needed. Each version of this function exists in two syntactical variants, one using named arguments and one with a pair of parameters. A named argument parameter_selector starts with an optional out keyword followed by an expression naming a shader output parameter, a colon, and a lvalue result, an expression that can be used left of an assignment operator, to hold the result value. The variant with a pair of parameters uses a string for the parameter selector and a second argument for the result. Note: The syntax variant with named arguments should be preferred. This function accepts a variable number of parameter_selector and result arguments. The parameter_selector argument specifies the output on the surface shader of the surface hit by the ray to be retrieved. Typically this is a Color or Spectrum output, but may be any MetaSL data type. All surface shaders should at minimum have an output named "result". The primary output is recommended to be the radiance in [W/(m2sr)] leaving the intersected surface in the inverse ray direction. Note that implementations of library functions may assume that this convention is followed. (See also section 22.1.3 of the MetaSL specification.) Interpretations of other output parameters are up to the user. The parameter_selector argument can also refer to a state variable, in which case the name should be prefixed with state::, for example: state::normal in the named argument syntax. This retrieves that value of the specified state variable as it appears at the intersection point of the cast ray. In the alternative syntax, the name should be prefixed with "State::", for example: "State::normal". For clarity a shader parameter name can also be prefixed with "Shader::" in the alternative syntax. If no prefix is specified, an output parameter is assumed. For each specified parameter_selector the value of that output will be stored in the corresponding result variable. The type T of the result variable must match the type of the requested output or both are either of type Color3, Color, or Spectrum and the value will be implicitly converted. Conversions from Color will drop the alpha value and conversion to Color will set the alpha value to one. In case of incompatible types, the trace() function will return false. A result variable keeps its original value in case the requested output does not exist or has the wrong type. The parameter_selector argument can also refer to a shader instance name, such as the name of an input parameter of type Shader, followed by a dot and an output parameter name of that shader. The shader instance will be called at the hit point, which means with the state of the hit point context. In general, the trace call can have several shader instance arguments as well as regular shader output arguments or state arguments. If the trace call does not contain parameter_selector arguments that refer to regular shader output parameter names, then the surface shader at the hit point will not be called at all. The following example traces a reflection ray along the direction of r and stores the standard Color result output in color, if it exists, or leaves color set to black: Color color(0.0, 0.0, 0.0, 1.0);trace(r, Trace_options(“reflect”), result: color); |
| int get_trace_depth(String ray_type) | Get the accumulated trace depth of the given ray type. The ray_type parameter must be a literal string and the value "total" can be used to request the total accumulated trace depth of all the ray types. |
| bool get_ray_data( String name, inout T value) |
Retrieves data set by ancestors of the current ray using Trace_options::set_ray_data().
name — Specifies the name of the data to access. If no data with the given name exists, this method will return false. value — Specifies a variable to hold the resulting value. The type T of this parameter can be any MetaSL type. If no data with the given name exists, the value of the variable remains unchanged. Once data is attached to a ray, the data will remain attached for all child rays. |
| void clear_ray_data(String name) void clear_ray_data() | Removes data set by ancestors of the current ray using Trace_options::set_ray_data(). This removal is effective for this shader and for child rays, but has no effect on the ancestors. The first version of clear_ray_data() removes data matching the specified name. If no data exists matching the given name, the method does nothing. The second version clears all ray data. |
| float occlusion( Occlusion_options options) |
Returns the ambient occlusion for the given point, which is 1.0 for full occlusion and 0.0 for no occlusion. |
| Spectrum irradiance( Irradiance_options options) | Returns the indirect irradiance in [W/m2] at the point within the cone specified by the options parameter, i.e., the incoming radiance which is not directly emitted onto the point, integrated over the cone. This function is commonly used for simple global illumination estimates, which assume that directly visible surfaces are fully diffuse. In that case, the BRDF fr(ωi,ωo) ≡ ρ/π does not depend on any direction, which allows it to be moved out of the radiance integral. This leads to (color/PI) * irradiance(). |
| bool get_shader_parameter( String parameter_name, inout T value) | Get a parameter value from the shader that invoked the light shader. The parameter_name argument must be a literal string. The type T of the value argument can be one of the basic built-in types. If no parameter with the given name exists, the value of the variable remains unchanged. |
| Spectrum shadowing() | Computes the shadow factor for the current light sample with respect to the surface point being shaded. The method used to determine the amount of shadow attenuation (for example shadow maps or ray traced shadows) can vary depending on the target platform. |
| bool exists_scene_data(String name) | Returns true if the queried
user scene data exists and false otherwise.
name — Specifies the name of the queried data. Arguments need to be constant expressions of type string. |
| T scene_data( String name, T default, ...) | Retrieves user
scene data by name from the scene description.
name — Specifies the name of the data to access. Arguments need to be constant expressions of type string. If no data with the given name exists, this method will return the default value. default — Specifies the default value that is returned in case no data with the given name exists. Furthermore, the type T of this value determines the return type and the type under which the data will be looked up. The type T can be any MetaSL type. ... — Optional parameters depending on the value of name. The types of these parameters can be any MetaSL type. |
| bool get_scene_data( String name, inout T value, ...) | Retrieves user scene data by
name from the scene description.
name — Specifies the name of the data to access. Arguments need to be constant expressions of type string. If no data with the given name exists, this method will return false. value — Specifies a variable to hold the resulting value. If no data with the given name exists, the value of the variable remains unchanged. Furthermore, the type T of this value determines the type under which the data will be looked up. The type T of this parameter can be any MetaSL type. ... — Optional parameters depending on the value of name. The types of these parameters can be any MetaSL type. |
| void error(String format, ...) void warning(String format, ...) void info(String format, ...) void progress(String format, ...) | These functions all output messages within their respective categories. The format string follows the C language printf function format specifier convention and is followed by a variable number of arguments. |
| Trace_options() | Default constructor. Defaults are documented with the individual methods below. |
| Trace_options(String ray_type) | Constructor initializing the ray type to ray_type. |
| Trace_options( String ray_type, String ray_dispersal_group) | Constructor initializing the ray type to ray_type and the ray dispersal group to ray_dispersal_group. |
| Trace_options( String ray_type, float near, float far) | Constructor initializing the ray type to ray_type and the distance from the origin of the ray at which intersecting testing begins and ends to near and far. |
| Trace_options( String ray_type, String ray_dispersal_group, float near, float far) | Constructor initializing the ray type to ray_type, the ray dispersal group to ray_dispersal_group, and the distance from the origin of the ray at which intersecting testing begins and ends to near and far. |
| void Trace_options::set_near(float near) | Set the distance from the origin of the ray at which intersection testing begins. Defaults to zero. |
| void Trace_options::set_far(float far) | Set the distance from the origin of the ray at which intersection testing ends. Defaults to an implementation specific positive huge value. |
| void Trace_options::set_ray_type( String ray_type) | Set
the ray type for the ray. Defaults to "reflect". This parameter
must be a literal string. The string "continue" can be
specified as a ray type in which case the current ray type will be
propagated to the new ray and tracing will continue as if the current
intersection did not take place.
If the ray type is set to "eye", "transparent", "refract", or "reflect" the scene is traced. And if nothing is hit and the environment shader is enabled (see the enable_environment method below) the environment shader is called if one exists. If the ray type is set to "shadow" or "occlusion" only the scene is traced. If the ray type is set to "environment" the environment shader is called without testing for other geometry intersections for the ray. |
| void Trace_options::set_ray_dispersal_group(
String ray_group) | Set the ray dispersal group. Defaults to "specular". This parameter must be a literal string. |
| void Trace_options::set_importance( float importance) void Trace_options::set_importance( Color3 importance) void Trace_options::set_importance( Color importance) void Trace_options::set_importance( Spectrum importance) | Specify the relative importance of the contribution from this ray with a value that ranges from 0 to 1 for each component. Defaults to 1. |
| void Trace_options::enable_environment( bool enabled) | Enables or disables the environment shader. If the environment shader is enabled (which is the default), it will be called if the ray doesn't intersect with scene geometry or the trace depth is exhausted. |
| void Trace_options::set_ray_data( String name, T value) |
Associates arbitrary data with rays that can
be read by shaders as the ray is traced. This data is associated with
the ray and all child rays until it is cleared by a shader. This data is
set in addition to data that has been set by ancestors of this ray. The
data is read and cleared with the state functions
get_ray_data() and clear_ray_data() described
below.
name — Specifies a name for the data. If a previous value with the same name exists it will be overwritten. value — Specifies the value to store. The type of this parameter can be any MetaSL type. It is important to note that the use of ray data can have costly effects on the performance of ray tracing and may even prevent the use of delayed ray tracing if the data size is too large. For that reason ray data should be used sparingly, preferably only to store a small number of Boolean flags. Note: This function is also available under the name set_data, as it was named in MetaSL 1.0. |
| Occlusion_options() | Default constructor. Defaults are documented with the individual methods below. |
| Occlusion_options( float near, float far) | Constructor initializing the distance from the origin of the ray at which intersecting testing begins and ends to near and far. |
| void Occlusion_options::set_near(float near) | Set the distance from the origin of the ray at which intersection testing begins. Defaults to zero. |
| void Occlusion_options::set_far(float far) | Set the distance from the origin of the ray at which intersection testing ends. Defaults to an implementation specific positive huge value. |
| void Occlusion_options::set_cone( float3 axis, float angle) void Occlusion_options::set_cone( float3 axis, float angle, float angle_exp) | Specify the cone over which the occlusion factor will be calculated. The axis parameter is specified as a normalized vector in internal space and defaults to the state normal. The angle parameter defaults to 90 (which corresponds to the whole hemisphere) and is measured in degrees. The angle_exp parameter defaults to 1 and corresponds to the exponent of the cosine-distribution used for weighting. |
| void Occlusion_options::set_importance(
float importance) void Occlusion_options::set_importance( Color3 importance) void Occlusion_options::set_importance( Color importance) void Occlusion_options::set_importance( Spectrum importance) | Specify the relative importance of the contribution from this ray with a value that ranges from 0 to 1 for each component. Defaults to 1. |
| Irradiance_options() | Default constructor. Defaults are documented with the individual methods below. |
| Irradiance_options( float near, float far) | Constructor initializing the shortest and furthest distance from the origin of the ray at which incoming light is considered to near and far. |
| void Irradiance_options::set_near( float near) | Set the shortest distance from the origin of the ray at which incoming light is considered. Defaults to zero. |
| void Irradiance_options::set_far(float far) | Set the furthest distance from the origin of the ray at which incoming light is considered. Defaults to an implementation specific positive huge value. |
| void Irradiance_options::set_cone( float3 axis, float angle) void Irradiance_options::set_cone( float3 axis, float angle, float angle_exp) | Specify the cone over which irradiance will be calculated. The axis parameter is specified as a normalized vector in internal space and defaults to the state normal. The angle parameter defaults to 90 (which corresponds to the whole hemisphere) and is measured in degrees. The angle_exp parameter defaults to 1 and corresponds to the exponent of the cosine-distribution used for weighting. |
| void Irradiance_options::set_importance(
float importance) void Irradiance_options::set_importance( Color3 importance) void Irradiance_options::set_importance( Color importance) void Irradiance_options::set_importance( Spectrum importance) | Specify the relative importance of the contribution from this ray with a value that ranges from 0 to 1 for each component. Defaults to 1. |