An interface class representing rendering kernel programs applied to surface primitives (e.g., IRegular_heightfield). More...

#include <irendering_kernel_programs.h>

Inherits mi::base::Interface_declare< 0x861e254b, ... >.

Detailed Description

An interface class representing rendering kernel programs applied to surface primitives (e.g., IRegular_heightfield).

The programs applied to surface geometries are evaluated for each surface intersection encountered during the rendering process. An example of a surface sample program is:

NV_IDX_XAC_VERSION_1_0
 
class Surface_sample_program
{
    NV_IDX_SURFACE_SAMPLE_PROGRAM
 
    float3 light_direction;
    float3 material_ka;     // ambient term
 
public:
    NV_IDX_DEVICE_INLINE_MEMBER
    void initialize()
    {
        light_direction = normalize(make_float3(1.0f, 1.0f, 1.0f));
        material_ka     = make_float3(0.1f, 0.1f, 0.1f);
    }
 
    NV_IDX_DEVICE_INLINE_MEMBER
    int execute(
       const   Sample_info_self&  sample_info,         // read-only
               Sample_output&     sample_output)       // write-only
    {
        if (sample_info.sample_color.w < 0.1f)
        {
            return NV_IDX_PROG_DISCARD_SAMPLE;
        }
 
        const float n_l          = dot(sample_normal, light_direction);
 
        const bool  soft_diffuse = false;
        const float diffuse      =   (soft_diffuse)
                                   ? n_l * 0.5f + 0.5f
                                   : max(0.0f, n_l);
 
        const float3 kd      = make_float3(sample_info.sample_color);
        const float3 s_lit   = material_ka + kd * diffuse;
 
        sample_output.color = make_float4(s_lit, sample_info.sample_color.w);
 
        return NV_IDX_PROG_OK;
    }
 
};

Currently the class representing a surface sample program needs to follow the template set in the example above. It has to be called Surface_sample_program and is required to expose two public methods called initialize(), which is executed once per rendering instance of a subregion, and execute(), which is then executed for each surface intersection encountered along a viewing ray.

Each surface sample program is also required to have the NV_IDX_SURFACE_SAMPLE_PROGRAM macro as the first definition inside the program class. This macro initializes the internal state of the program exposed to the user. Later revisions of the rendering kernel programs feature will make the definition more straightforward.

The initialize() method can be used to initialize variables used in the per-intersection computation of the execute() method. The initializations can encompass the calculation of static data such as lighting or material properties.

The execute() method always receives the current sample position, normal and color as input and the output color as output. The sample distance is passed as a modifiable reference to the method, which allows surface sample programs to override the intersection distance value individually. This feature can be utilized to implement custom depth-offset techniques to applicable surface geometries. Through the return value of this method the rendering kernel can be informed to use the generated output sample or to discard the current sample. For this purpose there are two return values for the execute() method:

NV_IDX_PROG_OK
NV_IDX_PROG_DISCARD_SAMPLE

The list of return values may be extended in the future to, for instance, discard entire ray segments.

In contrast to IVolume_sample_program instances, a surface sample program does currently not expose an internal state variable. This is subject to change in future revisions of this feature.

The documentation for this class was generated from the following file:

irendering_kernel_programs.h