BSL:Frustum and fog: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (+cat)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
See also [[wikipedia:Viewing_frustum]] and [[wikipedia:Distance_fog]]
==Frustum==
==Frustum==
:''In 3D computer graphics, the viewing frustum or view frustum is the region of space in the modeled world that may appear on the screen; it is the field of view of the notional camera. The exact shape of this region varies depending on what kind of camera lens is being simulated, but typically it is a frustum of a rectangular pyramid (hence the name). The planes that cut the frustum perpendicular to the viewing direction are called the near plane and the far plane. Objects closer to the camera than the near plane or beyond the far plane are not drawn. [[wikipedia:Image:ViewFrustum_01.png]]
:''See [[Graphics#Frustum|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 objects more than 100 meters away from the camera will be culled. The default distance of the far clipping distance is 10000 (1 kilometer).
;void gs_fov_set(float fov_degrees)
:(not available on PC demo or Mac) 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 defaut FOV and on a 4:3 screen, the horizontal viewing angle is 2*arctan(4/3*tan(45°/2))=57.8224°
;Widescreen FOV
:On a 16:9 or 16:10 screen, the horizontal viewing angle is larger: 2*arctan(16/9*tan(45°/2))=72.73435° and 2*arctan(16/10*tan(45°/2))=67.0682°, respectively. This causes insufficient frustum culling in some of Oni's cutscenes (intro sequences of {{C|2}}, {{C|11}}, and {{C|14}} for example). A quick way to fix this is to bring the horizontal viewing angle down to the supposed 57.8224° during the cutscene: the 4:3 viewport will then effectively be trimmed vertically rather than extended sideways. On 16:9 and 16:10 screens, the corrected vertical FOV will be 2*arctan(3/4*tan(45°/2))=34.515877° and 2*arctan(5/6*tan(45°/2))=38.0871°, respectively. Remember to set it back to 45° after the cutscene to fully enjoy the extended viewport.
;NOTE
: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.
;ALSO NOTE
:There is no control over Oni's ''near'' clipping plane: its distance is always 4 (40 cm).


;<tt>void [[gs_farclipplane_set]](float plane)</tt>
:This sets the distance of the far clipping plane in world units. If you call <code>[[gs_farclipplane_set]](1000)</code>, 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 plane 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 [[OBD:OTLF|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.)
;<tt>void [[gs_fov_set]](float fov_degrees)</tt>
: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 <code>[[gs_fov_set]](90)</code>, 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 (40 cm, or about 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 <code>[[gs_fov_set]](34.515877)</code> (because '''2 * arctan((4/3)/(16/9) * tan(45° / 2)) = 34.515877°''' ).
::To fix in on a 16:10 screen, use <code>[[gs_fov_set]](38.0871)</code> (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#Fog|Graphics]] for an explanation of fog and a reminder of frustum coordinates.''


==Distance fog==
===BSL interface===
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.
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:
The color components and their default values are:
:;float gl_fog_red= 0.25
:;<tt>float [[gl_fog_red]]=0.25</tt>
:;float gl_fog_green= 0.25
:;<tt>float [[gl_fog_green]]=0.25</tt>
:;float gl_fog_blue= 0.25
:;<tt>float [[gl_fog_blue]]=0.25</tt>
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 colorized to roughly match the dominant color of the skybox, which is not affected by fog). In {{C|1}}, {{C|2}}, {{C|10}} and {{C|12}}, the fog color is 15% gray. In {{C|3}}, the color has a red dominant: (0.3,0.17,0.15).
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 {{C|1}}, {{C|2}}, {{C|10}} and {{C|12}}, the fog color is 15% gray. In {{C|3}}, 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:
The "start" and "end" distances and their default values are:
:;float gl_fog_start= 0.925
:;<tt>float [[gl_fog_start]]=0.925</tt>
:;float gl_fog_end= 1.0
:;<tt>float [[gl_fog_end]]=1.0</tt>
Keep in mind that those "distances" are in frustum space: 1.0 corresponds to the far clipping plane, and 0.925 corresponds to a plane about 15.75 meters from the camera if the far clip plane is at 1 kilometer (see below for conversion rules).
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#Fog|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.
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.


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 <tt>[[gl_fog_start]]</tt> (and <tt>[[gl_fog_end]]</tt>) may be hard to guess, and you may want to have a look at the conversion formulas on the [[Graphics#Fog|Graphics]] page. You may also want to use smooth transitions rather than set the variables to new values instantly.
 
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 rules below. You may also want to use smooth transitions rather than set the variables to new values instantly.


The smooth transition functions are:
The smooth transition functions are:
:;void gl_fog_start_changeto(float start_val=0, int frames=0)
:;<tt>void [[gl_fog_start_changeto]](float start_val=0, int frames=0)</tt>
::If the far clip plane is at 10000, calling '''gl_fog_start_changeto(0.88, 60)''' moves the "start" of the fog gradient to about 3.3 meters in front of the camera, over one second.
::If the far clip plane is at 10,000 then calling <code>[[gl_fog_start_changeto]](0.88, 60)</code> 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.
::Calling <code>[[gl_fog_start_changeto]](0.88)</code> does the same instantly, since the default value of the <tt>frames</tt> argument is 0, and therefore has the same effect as <code>[[gl_fog_start]]=0.88</code>
:;void gl_fog_end_changeto(float end_val=0, int frames=0)
:;<tt>void [[gl_fog_end_changeto]](float end_val=0, int frames=0)</tt>
::If the far clip plane is at 10000, calling '''gl_fog_end_changeto(0.88001, 60)''' moves the "end" of the fog gradient to about 3.3 meters in front of the camera, over one second.
::If the far clip plane is at 10,000, calling <code>[[gl_fog_end_changeto]](0.88, 60)</code> 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.
::Calling <code>[[gl_fog_end_changeto]](0.88)</code> does the same instantly, since the default value of the <tt>frames</tt> argument is 0, and therefore has the same effect as <code>[[gl_fog_end]]=0.88</code>
 
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).
 
===Technical background===
:''For more technical information on fog and on frustum-based space (or whatever it's called), see [http://msdn2.microsoft.com/en-us/library/ms537113.aspx here] and [http://msdn2.microsoft.com/en-us/library/bb147268(VS.85).aspx here] and [http://cs.fit.edu/~wds/classes/graphics/PTOC/ptoc/ elsewhere].
 
The frustum (see above), defines a set of coordinates in which the near plane is at Z=0 and the far plane at Z=1 (X=-1 and X=1 correspond to the left and right side of the frustum; the top and bottom of the frustum are planes with Y=-a and Y=a, with '''a''' the aspect ratio of the screen).
 
The important thing for fog is Z (the depth coordinate in frustum-based space). Every pixel of every object within the frustum is blended with a color (the fog color), depending on the amount f of fog in front of that pixel. The default fog color is 25% gray.
 
For f<0, there is no fog in front of the object and the pixel retains its original color. For f>1 the object is completely fogged and the pixel has the color of the fog. For 0<f<1, the color is interpolated linearly between the original pixel color and that of the fog.
 
The value of f is taken to be 0 on the fog's "start" plane and 1 on the fog's "end" plane and is interpolated/extrapolated linearly elsewhere, in the frustum-based coordinates. The natural order is: near clip plane, fog "start" plane, fog "end" plane, far clip plane.


The conversion rule between z (actual distance from the camera) and Z (frustum-based depth) is:
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 <tt>[[gl_fog_end]]</tt> smaller than <tt>[[gl_fog_start]]</tt> (and make <tt>[[gl_fog_start]]</tt> small enough so that the player character is visible).
:Z = z_f * ( z - z_n ) / [ z * ( z_f - z_n ) ]
:z = z_n * z_f / [ z_f - Z*( z_f - z_n )]
By default, z_f is 10000 and z_n is 4, so Z=0.925 corresponds roughly to z=157.5


[[Category:Bungie scripting language docs]]
[[Category:Scripting tasks]]

Latest revision as of 13:31, 25 May 2020

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 plane 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 (40 cm, or about 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).