Raycasting and Illumination

Learn how to implement a raycasting system with SplashKit to simulate light rays and object illumination. This tutorial covers collision detection, dynamic ray length adjustment, and interactive visuals for game development or physics simulations.
Written by: Shaun Ratcliff
Last updated: 08 Dec 24

Full C# and Python code for this tutorial is still in development.

---

Introduction to Raycasting and Illumination

In this tutorial, you’ll learn how to implement a raycasting system that simulates illumination using SplashKit. This tutorial combines SplashKit’s physics and colour functions to show demonstrate dynamics. It will cover how to:

• Cast rays from a source to detect objects.
• Simulate illumination by varying object brightness based on ray intersection distance.
• Create an interactive environment where you dynamically adjust ray length by clicking the mouse.

By the end, you’ll understand the fundamental mechanics of raycasting and illumination, as well as how to leverage SplashKit’s built-in physics and colour functions to bring these concepts to life in your own projects.

Checkpoint!

We recommend you first familiarise yourself with the Raycasting Basics tutorial before proceeding with this one. This will provide you with a solid understanding of the fundamental principles of raycasting and how to effectively make use of the SplashKit functions.

Important SplashKit Functions Used in This Tutorial

1. Point Offset By
2. Vector Multiply
3. Vector To
4. Vector From Angle
5. HSB (Hue, Saturation, Brightness) Colour
6. Hue Of
7. Saturation Of
8. Brightness Of

Raycasting and Illumination

Raycasting can be used to simulate the behaviour of rays of light, projecting them through a scene to detect intersections with objects. It is a fundamental concept in computer graphics, physics simulations, and game development, providing a simple yet effective way to calculate line-of-sight visibility, lighting effects, and collision detection.

Illumination in the context of raycasting involves determining how objects in a scene interact with light, simulating brightness levels based on the distance of objects from the light source or the viewer. This adds a sense of realism, depth, and visual clarity, enhancing the user experience in games, simulations, and visual applications.

Why Raycasting and Illumination Are Useful

Raycasting is particularly valuable because of its simplicity and versatility. Unlike more complex rendering techniques such as ray tracing, which simulates every ray of light in a scene, raycasting focuses only on the most relevant rays. This makes it computationally efficient and suitable for real-time applications such as:

• Visibility Determination: Raycasting can calculate which objects or parts of a scene are visible from a particular point of view. This is useful for implementing features like line-of-sight in stealth games or player detection systems in AI logic.

• Collision Detection: By casting rays from a player or object, raycasting can identify obstacles or targets in the way, supporting mechanics like bullet trajectories, player movement restrictions, or object interaction.

• Lighting Effects: Illumination based on raycasting simulates how light interacts with objects, providing visual cues for depth, position, and mood. For example, a flashlight effect in a horror game or lighting in a top-down dungeon crawler.

Ray Generation

In this program, rays are generated from a single source point (the mouse cursor in this case) and cast in all directions. To create this effect, we divide the full circle (360 degrees) into equal segments based on the number of rays (NUM_RAYS).

Each ray is represented by a vector with a specific direction derived from its angle:

double angle_increment = 360.0 / NUM_RAYS;

for (int i = 0; i < NUM_RAYS; ++i)
{
    double ray_angle = i * angle_increment;         // Calculate the angle of the ray
    vector_2d ray_direction = vector_from_angle(ray_angle, 1.0);  // Generate a direction vector
}

Note

A higher number of rays creates more realistic illuminations, but may impact performance. Try to strike a balance between the two.

Ray Collisions

Once the rays are generated, the next step is to detect intersections with objects in the scene (rectangles and circles). The intersection points help determine if and where the rays interact with objects.

Collision with Rectangles

We use the ray_rectangle_intersection function to check whether a ray intersects with the edges of a rectangle. The function calculates entry and exit points for both the x and y bounds of the rectangle and determines the nearest intersection.

bool ray_rectangle_intersection(const point_2d &origin, const vector_2d &direction, const rectangle &rect, point_2d &hit_point, double &hit_distance)
{
    vector_2d inv_dir = vector_to(1.0 / direction.x, 1.0 / direction.y);
    double entry_distance_x = (rect.x - origin.x) * inv_dir.x;
    double exit_distance_x = (rect.x + rect.width - origin.x) * inv_dir.x;

    double entry_distance_y = (rect.y - origin.y) * inv_dir.y;
    double exit_distance_y = (rect.y + rect.height - origin.y) * inv_dir.y;

    double min_entry = std::max(std::min(entry_distance_x, exit_distance_x), std::min(entry_distance_y, exit_distance_y));
    double max_exit = std::min(std::max(entry_distance_x, exit_distance_x), std::max(entry_distance_y, exit_distance_y));

    if (min_entry > max_exit || max_exit < 0.0 || min_entry > MAX_RAY_DISTANCE)
        return false;

    hit_distance = min_entry;
    hit_point = point_offset_by(origin, vector_multiply(direction, min_entry));
    return true;
}

Collision with Circles

For circles, we use the circle_ray_intersection function. This function determines whether the ray intersects the circle within the allowed range and calculates the exact hit point.

bool circle_ray_intersection(const point_2d &origin, const vector_2d &heading, const circle &circ, point_2d &hit_point, double &hit_distance)
{
    float distance = ray_circle_intersect_distance(origin, heading, circ);
    if (distance < 0.0f || distance > MAX_RAY_DISTANCE)
        return false;

    hit_distance = static_cast<double>(distance);
    hit_point = point_offset_by(origin, vector_multiply(heading, hit_distance));
    return true;
}

Note

Rays can interact with any object that you desire, you will just need to create the logic for how the ray is meant to interact with the object. For example, if you wanted the ray to interact with a triangle that you created, you could implement something like the following:

Click to expand!

bool triangle_ray_intersection(const point_2d &origin, const vector_2d &heading, const triangle &tri, point_2d &hit_point, double &hit_distance)
{
    if (point_in_triangle(origin, tri))
    {
        hit_point = origin;
        hit_distance = 0.0;
        return true;
    }

    bool has_collision = false;
    double closest_distance = __DBL_MAX__;

    // Iterate through each edge of the triangle
    for (int i = 0; i < 3; ++i)
    {
        point_2d start_point = tri.points[i];         // Start point of the edge
        point_2d end_point = tri.points[(i + 1) % 3]; // End point of the edge

        vector_2d edge_vector = vector_point_to_point(start_point, end_point); // Edge vector
        vector_2d origin_to_edge = vector_point_to_point(origin, start_point);

        // Cross product to determine parallelism
        double cross_ray_and_edge = (heading.x * edge_vector.y) - (heading.y * edge_vector.x);
        if (std::fabs(cross_ray_and_edge) < 1e-8)
            continue; // Skip edges nearly parallel to the ray

        // Calculate intersection parameters
        double ray_parameter = ((origin_to_edge.x * edge_vector.y) - (origin_to_edge.y * edge_vector.x)) / cross_ray_and_edge;
        double edge_parameter = ((origin_to_edge.x * heading.y) - (origin_to_edge.y * heading.x)) / cross_ray_and_edge;

        // Check if intersection occurs within the edge and along the ray
        if (ray_parameter >= 0.0 && edge_parameter >= 0.0 && edge_parameter <= 1.0)
        {
            // Compute the intersection point
            vector_2d scaled_ray = vector_multiply(heading, ray_parameter);
            point_2d current_intersection = point_offset_by(origin, scaled_ray);

            // Check if this is the closest intersection
            double distance_to_intersection = vector_magnitude(vector_point_to_point(origin, current_intersection));
            if (distance_to_intersection < closest_distance)
            {
                closest_distance = distance_to_intersection;
                hit_point = current_intersection;
                has_collision = true;
            }
        }
    }

    if (has_collision)
    {
        hit_distance = closest_distance;
    }
    return has_collision;
}

Applying Illumination

The brightness of objects is determined by the distance between the source and the intersection point. Closer objects appear brighter, while farther objects fade. The brightness is linearly scaled based on the intersection distance relative to the maximum ray distance (MAX_RAY_DISTANCE).

double calculate_brightness(double distance)
{
    return std::max(0.0, 1.0 - (distance / MAX_RAY_DISTANCE));  // 1.0 at origin, 0.0 at max distance
}

Once a ray intersects an object, its brightness is calculated, and the object’s colour is adjusted accordingly.

double brightness = calculate_brightness(intersection_distance);
color rect_color = hsb_color(hue_of(COLOR_PURPLE), saturation_of(COLOR_PURPLE), brightness);

The hsb_color function simplifies dynamic colour changes, allowing you to adjust brightness without modifying an object’s base hue or saturation.

The hsb_color Function

hsb_color is used to dynamically adjust the brightness of objects based on their interaction with rays. This function allows us to modify an object’s hue, saturation, and brightness (HSB), enabling realistic illumination effects.

When a ray intersects an object, the brightness component of its colour is calculated based on the distance of the intersection point from the light source. Closer objects appear brighter, while those farther away fade into darkness. This is achieved without altering the object’s original hue or saturation, ensuring its base colour remains consistent.

Tip

To change things up, you could even change colours based on their proximity to the light, similar to a heat map, with red meaning close and blue meaning far!

Putting it All Together

Now that we’ve covered the individual components of the raycasting and illumination system, let’s see how they work together in a full program. We’ll combine ray generation, collision detection, and dynamic illumination to create a responsive visual system. Click the Test Code in SplashKit Online button below to load the SplashKit Online IDE and run the code yourself. The code demonstrates:

• Raycasting: Generates rays from the mouse cursor and casts them in all directions (360 degrees) to detect objects.
• Dynamic Interaction: Allows dynamic adjustment of ray length by clicking the left mouse button, cycling through predefined distances.
• Collision Detection: Detects intersections between rays and scene objects (rectangles and circles).
• Illumination Simulation: Calculates brightness for objects based on their distance from the light source, making closer objects brighter.
• Real-time Visualisation: Visualises rays and illuminated objects in real time as the mouse moves through the scene.

Test Code in SplashKit Online

Conclusion

In this tutorial, we’ve implemented a raycasting system in SplashKit to simulate light and object illumination. This foundation can be expanded further for use in games or simulations, with opportunities to add new objects, refine collision logic, or explore advanced visual effects. Modify the code to fit your needs and experiment with SplashKit’s functions to explore new possibilities.