BSL:Frustum and fog

Frustum

See Graphics for an explanation of frustum.

void gs_farclipplane_set(float plane)

This sets the distance of the far clipping plane in world units. If you call gs_farclipplane_set(1000), then all polygons whose closest point is more than 1,000 world units (83 ft) away from the camera will be culled. The default distance of the far clipping distance is 10,000 world units (833 ft).

void gs_fov_set(float fov_degrees)

This sets the angle between the top and bottom planes of the frustum. If you call gs_fov_set(90), then the angle at the camera between the top and bottom of the frustum will be 90°. The default value of that angle is 45°.

The aspect ratio of the frustum stays constant (defined by the current screen resolution), so the view will get wider as you increase the vertical FOV. For the default FOV and on a 4:3 screen, the horizontal viewing angle is 2 * arctan(4/3 * tan(45° / 2)) = 57.8224°

Notes

The far clip plane and FOV are only reset when Oni starts, not when you load a level, so mind their default values and the side effect of other scripts.

There is no control over Oni's near clipping plane: its distance is always 4 units (16 inches).

Fog

See Graphics for an explanation of fog.

There are 5 fog-related variables: 3 color components (RGB) and 2 distances in frustum space (see below) between which the fog gradient builds up. All five values are reset to their default values at level load.

The color components and their default values are:

float gl_fog_red=0.25

float gl_fog_green=0.25

float gl_fog_blue=0.25

This corresponds to dark gray (25% gray). For nighttime and outdoors environments, the three components are typically set to 0 (black fog), but in daytime or indoors environments the fog/haze color may be brighter (and possibly chosen to roughly match the dominant color of the skybox, which is not affected by fog). In CHAPTER 01 . TRIAL RUN, CHAPTER 02 . ENGINES OF EVIL, CHAPTER 10 . CAT AND MOUSE and CHAPTER 12 . SINS OF THE FATHER, the fog color is 15% gray. In CHAPTER 03 . PUZZLE PIECES, the color red is dominant: (0.3, 0.17, 0.15).

The "start" and "end" distances and their default values are:

float gl_fog_start=0.925

float gl_fog_end=1.0

Keep in mind that those "distances" are percentages of the frustum length: 1.0 corresponds to the far clipping plane, so 0.925 corresponds to a plane about 17.7 feet from the camera if the far clip plane is at its default 833 feet (see Graphics for conversion formulas).

That the "end" fog plane is at 1.0 means that the fog will completely hide objects only at the far end of the viewing frustum. Objects closer than the "start" fog plane won't be affected by fog at all. In between, there will be a fog gradient.

Typically, tweaking the "start" plane is enough to achieve a good-looking distance fog: once set, the fog/haze can be kept the same for the whole level. However, in some situations (e.g., in the dream level), the fog starts closer to the player.

In that case the correct values of gl_fog_start (and gl_fog_end) may be hard to guess, and you may want to have a look at the conversion formulas on the Graphics page. You may also want to use smooth transitions rather than set the variables to new values instantly.

The smooth transition functions are:

void gl_fog_start_changeto(float start_val=0, int frames=0)

If the far clip plane is at 10,000, calling gl_fog_start_changeto(0.88, 60) moves the "start" of the fog gradient to about 11.1 feet in front of the camera, over one second.

Calling gl_fog_start_changeto(0.88) does the same instantly, since the default value of the frames argument is 0.

void gl_fog_end_changeto(float end_val=0, int frames=0)

If the far clip plane is at 10,000, calling gl_fog_end_changeto(0.88001, 60) moves the "end" of the fog gradient to about 11.1 feet in front of the camera, over one second.

Calling gl_fog_end_changeto(0.88) does the same instantly, since the default value of the frames argument is 0.

Note that you can invert the effect, to obtain short-distance fog rather than the usual long-distance fog. All you have to do is to make gl_fog_end smaller than gl_fog_start (and gl_fog_start small enough so that the player character is visible).