Documentation: photonics.glsl

/photonics/photonics.glsl (since v0.3.0)

The main photonics API file. Requires #version 430.

Tracing

The API responsible for raytracing, usable in every pass/program.

RayJob (since v0.3.0)

struct RayJob {
    vec3 origin; // The origin of the ray in rt space. (E.g real_origin - world_offset)
    vec3 direction; // The direction of the ray.

    vec3 result_position; // The position of the hit voxel in rt space.
    vec3 result_normal; // The geometry normal of the voxel that was hit
    vec3 result_color; // The color of the voxel that was hit
    bool result_hit; // true if the ray hit a voxel
};

Represents a ray, used by trace_ray.

ray_constraint (since v0.3.0)

ivec3 ray_constraint;

When set limits raytracing to a single block in rt space at ray_constraint. To remove the constraint set ray_constraint to ivec3(-9999).

result_tint_color (since v0.3.0)

vec3 result_tint_color;

The cumulative tint color applied to lighting after a call to trace_ray. This is always vec3(1f) when photonics.alphaMode is set to none.

This defaults to absorption, but can be changed with #PH_USE_CUSTOM_ALPHA and #PH_ALPHA_FUNC.

result_block_id (since v0.3.0)

int result_block_id;

The block id of the block that was hit.

get_result_sky_light (since v0.3.0)

int get_result_sky_light(vec3 normal);

The skylight level of the hit block, where normal is one of the faces of the block. Ranges from 0 to 15.

trace_ray (since v0.3.0)

void trace_ray(
    inout RayJob job, // The ray to trace
    bool transparency // Whether or not to pass through transparent voxels. This does nothing when `photonics.alphaMode` is set to `none`.
);

Raytracing primitive. See documentation for RayJob for more details.

void trace_ray(
    inout RayJob job // The ray to trace
);

An overload of trace_ray(RayJob, bool) where transparency is set to false.

Light List

Photonics compiles & tracks its own list of lights, with a max capacity of photonics.maxLights, usable in every pass/program.

Light

struct Light {
    int index; // The index of the light in the light list. Values less than zero are used for handheld lights (-1 for main hand, -2 for offhand)
    int blockId; // The block ID of the light, or -1 if the light is an enchanted item.
    vec3 position; // The position of the light in RT space
    vec3 color; // The SRGB color of the light, multiplied by intensity.
    float intensity; // The intensity of the light.
    vec2 attenuation; // The attenuation factor for the light.
    float falloff; // The falloff value for the light.
    float block_radius; // The radius of the light, in blocks.
};

Represents a light. Used for both placed lights & handheld lights.

Fields such as intensity, attenuation, and falloff do not have a 1 to 1 correspondence to their values in ph_lights.json. More information about the usage of each field can be found in the documentation for attenuation_modifier.glsl

load_light

Light load_light(int index);

Returns the light at . Indices beyond ph_light_count will have garbage data.

load_main_hand_light

Light load_main_hand_light();

Returns the light held in the players main hand. You should make sure the player is actually holding a light before invoking this method (see main_hand_has_light).

load_off_hand_light

Light load_main_hand_light();

Returns the light held in the players offhand. You should make sure the player is actually holding a light before invoking this method (see off_hand_has_light).

ph_lights_array_mapping

layout (std430) restrict readonly buffer ph_light_list_mapping {
    int ph_lights_array_mapping[];
};

A mapping for lights when the light list changes. Will be -1 when the light was removed.

Usage:

// The index of a light from the previous frame
int previous_index; // Make sure previous_index is the range 0..<MAX_LIGHTS
int new_index = ph_lights_array_mapping[previous_index]; 

if (new_index == -1) // Handle missing light

Light Binning

When photonics.enableLightBinning = true (or when using simple lighting!) Photonics will compile lights into 8x8x8 block sized bins. Each bin contains the N (photonics.maxSamples) lights with the highest contribution to the center of the bin. These bins internally use the default attenuation, and cannot be changed. One should be careful when using large bin sizes as it is the main factor to build time, and increases memory usage (equal to 64^3 * (1 + MAX_SAMPLES) * 4 bytes).

This API is only available when light binning is enabled.

load_light_offset

int load_light_offset(vec3 rt_pos);

light_registry_array

layout (std430) restrict readonly buffer light_registry_block {
    int light_registry_array[];
};

The buffer used for light binning. Offsets into the buffer are obtained with load_light_offset.

offset + 0 is the number of lights in the bin offset + n is the index for the nth light in the bin.

Each bin is sorted by contribution, so offset + 1 is the light with the highest contribution to the bin.

Example usage:

vec3 rt_pos;
int offset = load_light_offset(rt_pos);

int bin_size = light_registry_array[offset + 0];

for (int i = 0; i < bin_Size; i++) {
    Light light = load_light(offset + i + 1);
    // Use the light
}

Misc

Usable in every pass/program.

get_block_id

int get_block_id(vec3 rt_pos);

Returns the block at id at rt_pos, or PH_AIR_ID if PH_USE_CUSTOM_AIR_ID is defined and the block is air.