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 (328.084 ft, or 100 m) away from the camera will be culled. The default distance of the far clipping distance is 10,000 world units (3,280.84 ft, or 1,000 m).

(The maximum size of the visible world is 819.2 x 819.2 x 819.2 m, see HERE. Therefore the default far clip distance imposes no restriction at all, unless the camera is taken far away from the center of the world.)

void gs_fov_set(float fov_degrees)

This sets the vertical field-of-view (FOV) in degrees (°), i.e., the angle between the top and bottom planes of the frustum as measured at the camera's location. 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).

The fixed vertical FOV is why some of Oni's cutscenes were broken when 16:10 and 16:9 screens appeared.

To fix in on a 16:9 screen, use gs_fov_set(34.515877) (because 2 * arctan((4/3)/(16/9) * tan(45° / 2)) = 34.515877° ).

To fix in on a 16:10 screen, use gs_fov_set(38.0871) (because 2 * arctan((4/3)/(16/10) * tan(45° / 2)) = 38.0871° ).

Be sure to restore the default FOV value after the cutscene if you want to have the wider field-of-view when playing.

Fog

See Graphics for an explanation of fog and a reminder of frustum coordinates.

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, which takes place at sunset, 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 and are measured in frustum space: 1.0 corresponds to the far clipping plane, so 0.925 corresponds to a plane about 17.411 feet (or 5.307 m) from the camera if the far clip plane is at its default 3,280.84 ft (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), there is a much thicker fog that starts at a closer distance to the player and builds up to its maximum value over a shorter distance as well.

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 then 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 (60 frames).

Calling gl_fog_start_changeto(0.88) does the same instantly, since the default value of the frames argument is 0, and therefore has the same effect as gl_fog_start=0.88

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.88, 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, and therefore has the same effect as gl_fog_end=0.88

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 make gl_fog_start small enough so that the player character is visible).