IblEnvironment

class IblEnvironment

Bases: TypedReferenceCount

The image-based light of the PBR shader: an environment’s radiance, prefiltered for GGX, and its irradiance as spherical harmonics.

The source is a cube map or an equirectangular panorama (a 2-D texture), in linear light: float or half-float data, or 8-/16-bit data (sRGB formats are decoded). Directions are world directions with Acron’s Z up, as the shader looks them up: a cube map texel is seen along the direction OpenGL’s cube lookup gives it, and a panorama’s column and row follow longitude atan2(x, y) and latitude asin(z), as PanoramaRemap::equirect_to_cube_face reads them.

The radiance is a size x size cube map with a full mipmap chain. Level 0 is the source (area-filtered to the size); level l < levels holds the split-sum prefiltered radiance of perceptual roughness l / (levels - 1) (Karis, “Real Shading in Unreal Engine 4”, SIGGRAPH 2013): GGX importance samples (a Hammersley set) with N = V = R, weighted by N.L, each read from the source mip whose texel matches the sample’s solid angle (Krivanek and Colbert, “Real-time Shading with Filtered Importance Sampling”, 2008). The levels below are box-filtered, so the chain is complete. The data is RGBA16F.

The irradiance is the source projected on the nine real spherical harmonics up to l = 2 (the shader convolves them with the cosine lobe; Ramamoorthi and Hanrahan 2001), with exact texel solid angles.

The prefilter runs on the CPU, on a few worker threads, and releases the GIL. The result depends only on the inputs (for one platform’s libm): write() and read() cache it as a file. apply() puts it on a node as the inputs of pbr_ibl.glsl: pbr_env_radiance, pbr_env_sh and pbr_env_params.

The values are radiance in nits when the source is calibrated; otherwise set an intensity, which scales both the radiance and the irradiance.

Inheritance diagram

digraph inheritancea7e2ef104d { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "IblEnvironment" [URL="acron.shading.IblEnvironment.html#acron.shading.IblEnvironment",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedReferenceCount" -> "IblEnvironment" [arrowsize=0.75,style=""]; "ReferenceCount" [URL="acron.core.ReferenceCount.html#acron.core.ReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "ReferenceCount" [arrowsize=0.75,style=""]; "TypedObject" [URL="acron.core.TypedObject.html#acron.core.TypedObject",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "TypedObject" [arrowsize=0.75,style=""]; "TypedReferenceCount" [URL="acron.core.TypedReferenceCount.html#acron.core.TypedReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedObject" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; "ReferenceCount" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; }

IblEnvironment.__init__()

An empty, invalid environment (for read()).

Prefilters the source (a cube map or an equirectangular panorama with a RAM image) into a size x size cube with levels roughness levels and samples GGX samples per texel. On an unreadable source the environment is black and is_valid() is false.

IblEnvironment.apply()

Puts the environment on a node as the PBR shader’s image-based light: pbr_env_radiance, pbr_env_sh and pbr_env_params (x: the mip level of roughness 1; y: the intensity times the storage scale). Call it again after changing the intensity.

static IblEnvironment.get_class_type()

static IblEnvironment.get_cube_direction()

The world direction (not normalised) that OpenGL’s cube lookup maps to face (0-5: +X, -X, +Y, -Y, +Z, -Z) at texture coordinates s, t in [0, 1]; t = 0 is the face’s first row in RAM.

IblEnvironment.get_intensity()

See set_intensity().

IblEnvironment.get_irradiance()

The irradiance divided by pi that the shader computes from the SH for a world normal (a uniform environment of L nits gives L), before the intensity.

IblEnvironment.get_num_levels()

The prefiltered levels: level l holds roughness l / (levels - 1).

IblEnvironment.get_num_sh()

The spherical-harmonic coefficients: nine, L00 to L22.

IblEnvironment.get_radiance()

The prefiltered radiance as a cube map (RGBA16F, full mipmap chain, trilinear filtering), made on first call: the shader’s pbr_env_radiance. Its texels are the radiance divided by a power-of-two storage scale (1 unless the source exceeds half-float range), which apply() passes on.

IblEnvironment.get_samples()

GGX importance samples per texel of the prefiltered levels.

IblEnvironment.get_sh()

Spherical-harmonic coefficient i (0-8: L00, L1-1, L10, L11, L2-2, L2-1, L20, L21, L22) of the radiance, before the intensity.

IblEnvironment.get_size()

The width and height of the radiance cube map’s faces at level 0.

IblEnvironment.get_storage_scale()

The power of two that the stored texels are divided by, so that the brightest fits in half-float range: 1 for most environments. apply() multiplies it back in through pbr_env_params.y.

IblEnvironment.get_texel()

The radiance of one texel of the cube’s mip level (0 is the source; level l < num_levels is roughness l / (num_levels - 1)), as stored (half floats) times the storage scale, before the intensity. Row y = 0 is the first row in RAM, t = 0 of OpenGL’s cube lookup.

IblEnvironment.is_valid()

False when the source could not be read (an unsupported texture or a corrupt file); the environment is then black.

static IblEnvironment.make_uniform()

An environment of the same radiance in every direction (nits, linear), e.g. for a white furnace test or a plain overcast ambient.

static IblEnvironment.read()

Reads an environment that write() wrote. Returns nullptr, with an error, when the file is missing, corrupt or of another version.

IblEnvironment.sample()

The radiance the shader reads in a world direction at a perceptual roughness (0-1), before the intensity: a trilinear lookup of the prefiltered cube, bilinear within a face (the GPU also filters across face edges).

IblEnvironment.set_intensity()

A scale on the radiance and the irradiance, applied by the shader (pbr_env_params.y): 1 for a source in nits.

IblEnvironment.write()

Writes the environment (the prefiltered cube and the SH) to a file that read() loads without prefiltering again.