Creating Point Clouds

Point clouds provide a way to dynamically affect the lighting applied to objects that move around in your game. A point cloud is essentially a collection of points, each defined by a position in 3D space and a normal. When you render your scene, the lighting effect at each point in the cloud is calculated. As your characters or other dynamic objects move around in your game engine at runtime, you can apply these lighting effects to the models to increase the realism and dynamic quality of your scene.

For example, suppose your scene has a hallway with a bright yellow light at one end and a bright blue light at the other. If a character walks down the hallway without any change to the way its model is rendered under the different lights, the realism of the game will suffer. However, if you create a point cloud down the length of the hallway, you can use the lighting information generated for the points in that cloud to alter the shading on your character dynamically as it moves along the corridor.

In this scenario, the lighting applied to the point closest to the yellow light source will contain a large contribution from the yellow light source, the lighting applied to the point at the other end of the hallway will contain a large contribution from the blue light source. A point in the middle will have a balanced contribution. At each frame as your characters move around, you apply the light contribution from the nearest point in the cloud to the character's model. Typically, you would interpolate the contributions from the nearest set of points proportionally to their distance to the model. Therefore, as the character moves from one end of the hallway to the other, its lighting shifts gradually from yellow to bluish.

Point clouds are not exact; they represent a way to fake color bleeding and global illumination for dynamic meshes that is good enough to appear real in most cases while still attaining relatively good runtime performance.

Setting up a point cloud

You can only set up a point cloud in the context of setting up a scene. See also Creating a Scene.

To set up a point cloud:

Create a new ILBPointCloudHandle.
Initialize the handle by calling ILBCreatePointCloud(). In your call, you have to specify the handle of the scene that will contain your point cloud.
Add points to the cloud by calling ILBAddPointCloudData(). You can call this method multiple times to add points in batches; this can help to reduce temporary memory consumption.
Finalize the point cloud handle by calling ILBEndPointCloud(). Once you have finalized the point cloud, you can no longer modify it, but it will be ready for rendering.

For example, the following code sets up a simple 5 by 5 grid of points:

ILBPointCloudHandle pch;
ILBCreatePointCloud(scene, _T("MyPointCloud"), &pch);

std::vector<ILBVec3> normals;
normals.resize(5, ILBVec3(1, 0, 0));

ILBVec3 minCorner(-9.95f, -9.95f, -9.95f);
ILBVec3 maxCorner(9.95f, 9.95f, 9.95f), 10);
ILBVec3 sideLength(maxCorner.x - minCorner.x, maxCorner.y - minCorner.y, maxCorner.z - minCorner.z);

for (int32 z = 0; z < 5; z++) {
    for (int32 y = 0; y < 5; y++) {
        std::vector<ILBVec3> points;
        points.reserve(5);
        for(int x = 0; x < 5; ++x) {
            float xx = minCorner.x + sideLength.x * (float)x / (float)(4);
            float yy = minCorner.y + sideLength.y * (float)y / (float)(4);
            float zz = minCorner.z + sideLength.z * (float)z / (float)(4);
            points.push_back(ILBVec3(xx, yy, zz));
        }
        ILBAddPointCloudData(pch, &points[0], &normals[0], 5);
    }
}
ILBEndPointCloud(pch);

Thread safety

You should only modify a point cloud from a single thread at a time.

Related API functions

API functions related to the creation and setup of point clouds are declared in the beastpointcloud.h file.