View source for Shaders in Oolite: uniforms

:<small>The information presented on this page applies to Oolite test release 1.69 and later.</small>

A '''uniform''' in a [[Shaders in Oolite|shader]] is a variable whose value is specified by the host application – in this case, [[Oolite]]. Oolite allows arbitrary uniforms to be specified for shaders applied to ships, and these may either take constant values specified in ''shipdata.plist'', or be “bound” to an attribute of the ship. This allows shader authors to access numerous properties of a game entity without having to ask for them and wait for an updated version of Oolite. ('''Note:''' in the case of subentities, bound properties are fetched from the parent ship.)

=== Basic syntax ===
Uniforms are specified in the ''materials'' or ''shaders'' dictionary of a ship’s ''shipdata.plist'' entry:
 <font color="#AAAAAA">"ahruman_shady_cobra_example" =</font>
 <font color="#AAAAAA">{</font>
 <font color="#AAAAAA">    like_ship = "cobra3-player";</font>
 <font color="#AAAAAA">    shaders =</font>
 <font color="#AAAAAA">    {</font>
 <font color="#AAAAAA">        "cobra3_redux.png" =</font>
 <font color="#AAAAAA">        {</font>
 <font color="#AAAAAA">            textures = ( "cobra3_redux.png" );</font>
 <font color="#AAAAAA">            fragment_shader = "ahruman_shady_cobra_example.fragment";</font>
             uniforms =
             {
                 shininess =
                 {
                     type = float;
                     value = 42.0;
                 };
                 withinAegis = "withinStationAegis";
                 compassMode = "compassMode";
             }
 <font color="#AAAAAA">        }</font>
 <font color="#AAAAAA">    }</font>
 <font color="#AAAAAA">}</font>
This contrived example declares three uniforms, ''shininess'', ''withinAegis'' and ''compassMode''. ''shininess'' is a constant <code>float</code>; it is always 42. ''withinAegis'' is bound to the ship’s ''withinStationAegis'' property. (See below for information on available properties.) This is a boolean, that is, a number whose value is either 0 (meaning no) or 1 (meaning yes). ''compassMode'' is a binding to the ''compassMode'' property. To use the uniforms within a shader (either a vertex shader or a fragment shader), they are declared as follows:
 uniform float shininess;
 uniform int withinAegis;
 uniform int compassMode;
 ...
 void main(void)
 {
     if (withinAegis)
     {
          // Do aegis-specific effect here
     }
     ...
 }

=== Uniform property types ===
Every bindable property has a '''type'''. The simplest types, ''int'' and ''float'', correspond directly to the same types in GLSL. Both represent numbers, with the difference that a ''float'' can represent fractional values and very large values, but always has the same level of precision (about six digits), while ''int''s can represent any integer (non-fractional value) in a limited range. A ''bool'' is an integer whose value can be only 0 (meaning no or false) or 1 (meaning yes or true). ('''Note:''' the GLSL specification is deliberately vague on the ranges of the number types. It also points out that most hardware will actually use floating-point calculations for ''int'' variables, which implies that integer calculations will incur rounding overhead.)

The ''vector'' type is translated to a GLSL ''vec4'', whose ''x'', ''y'' and ''z'' components correspond to those of the Oolite vector, and whose ''w'' component is always 1.0.

The ''quaternion'' type can be translated to a ''mat4x4'' representing a rotation matrix, or to a ''vec4'' whose ''x'', ''y'', ''z'' and ''w'' components correspond to those of the Oolite quaternion.

The ''matrix'' type is translated into a GLSL ''mat4x4''.

The ''colour'' type is translated into a GLSL ''vec4'' type, whose ''r'', ''g'', ''b'' and ''a'' components correspond to those of the Oolite colour object.

==== Conversions ====
Several types of binding can be modified by conversion options, specified in the '''uniforms''' dictionary, for example:
 haveFuel =
 {
     binding = "fuel";
     clamped = true;
 };
The '''clamped''' conversion option, when applied to a property of type ''float'', causes the value to be clamped to the range [0, 1]. When applied to an ''int'' propertie, any value other than 0 (including negative values) is converted to 1. The default value is ''false''.

The '''normalized''' option causes vector properties to be normalized, that is, scaled so they have the same direction but length 1. The default value is ''false''.

The '''asMatrix''' option causes quaternion properties to be converted to rotation matrix, rather than having their components packed into a ''vec4''. The default value is ''true''.

=== Bindable property reference ===
The following sections list entity properties which can be used in a uniform binding, regardless of apparent usefullness. Note, however, that '''some of these names may change before the next stable release'''.

==== Entity ====
The following properties are available for all entities:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable entity properties
! Name !! Type !! Description
|-
| ''position'' || vector || The location of the entity in system co-ordinates.
|-
| ''orientation'' || quaternion || The orientation of the entity.
|-
| ''relativePosition'' || vector || The location of the entity, relative to the player.
|-
| ''viewpointOffset'' || vector || The location of the current camera, in entity co-ordinates. Although this is defined for all entities, it is only meaningful for the player ship.
|-
| ''collisionRadius'' || float || Together with the ''position'', specifies a sphere completely containing the collidable volume of the entity.
|-
| ''mass'' || float || The mass of the entity.
|-
| ''energy'' || float || The current energy level of the entity.
|-
| ''maxEnergy'' || float || The current maximum energy level of the entity.
|-
| ''universalTime'' || float || The [[Time scales in Oolite#game real time|game real time]] clock. The value is the same for all entities and updates once per frame.
|-
| ''spawnTime'' || float || The [[Time scales in Oolite#game real time|game real time]] at which the entity came into existance.
|-
| ''timeElapsedSinceSpawn'' || float || The number of seconds (in the [[Time scales in Oolite#game real time|game real time]] scale) since the entity came into existance – the difference between ''universalTime'' and ''spawnTime''.
|-
| ''throwingSparks'' || bool || Whether the entity is generating sparks (for instance, a ship about to explode).
|-
|}



==== Ship ====
Ships (i.e., anything set up in ''shipdata.plist'', regardless of function) have all the properties of [[#Entity|entities]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable ship properties
! Name !! Type !! Description
|-
| ''isBeacon'' || bool || True if the entity is a beacon.
|-
| ''isFrangible'' || bool || True if the entity is frangible, i.e. subentities can be shot off.
|-
| ''isCloaked'' || bool || True if the entity is cloaked. [b]Note:[/b] a cloaked ship will only be drawn approximately once per ten frames, regardless of shaders.
|-
| ''isJammingScanning'' || bool || True if the ship has an active military jammer.
|-
| ''hasMilitaryScannerFilter'' || bool || True if the ship has a military scanner filter.
|-
| ''messageTime'' || float || Time before a radio message may be sent, in seconds. (This is set to 6.0 seconds when an NPC ship sends a message, and decreases over time.)
|-
| ''groupID'' || int || Unique identifier for the escort group the ship belongs to.
|-
| ''escortCount'' || int || The number of active escorts the ship has.
|-
| ''hasHostileTarget'' || bool || True if the ship has a target and the ship’s current AI behaviour is one of hostile intent.
|-
| ''weaponRange'' || float || Maximum range (in metres) of the ship’s main weapon. [b]Note:[/b] since subentities’ shaders get the parent ship’s properties, this may not work as expected.
|-
| ''scannerRange'' || float || The distance (in metres) in which the ship will scan for enemies.
|-
| ''withinStationAegis'' || float || True if the ship is within the aegis of the system’s main station.
|-
| ''fuel'' || int || Ship’s fuel level, in tenths of a light year.
|-
| ''flightPitch'' || float || Current pitch rate.
|-
| ''flightRoll'' || float || Current roll rate.
|-
| ''flightYaw'' || float || Current yaw rate. Currently always 0 for NPC ships.
|-
| ''flightSpeed'' || float || Ship’s current speed.
|-
| ''maxFlightSpeed'' || float || Ship’s speed at full throttle. Something of a misnomer – actual speed may be higher using afterburners or hyperspeed.
|-
| ''speedFactor'' || float || ''flightSpeed'' divided by ''maxFlightSpeed''. May be greater than 1.0 (unless [[#Conversions|clamped]] is used).
|-
| ''damage'' || int || ''energy'' expressed as a percentage of ''maxEnergy''.
|-
| ''laserHeatLevel'' || float || The temperature level of the current weapon.
|-
| ''hullHeatLevel'' || float || The temperature level of the hull, due to proximity to stars, atmospheric drag or combat hits. When it reaches 1.0, the ship starts taking damage rapidly.
|-
| ''entityPersonality'' || float || A randomly-generated value in the range 0.0 to 1.0 that stays with the entity for its lifetime. Useful for adding random variations.
|-
| ''entityPersonalityInt'' || float || Same as ''entity_personality'', scaled to the range 0 to 32767.
|-
| ''numberOfScannedShips'' || int || The number of ships within scanner range (but no more than 16).
|-
| ''destination'' || vector || The location, in system co-ordinates, that the AI is trying to fly to. This may not always be meaningful depending on AI state.
|-
| ''rangeToDestination'' || float || The distance in metres between ''position'' and ''destination''.
|-
| ''rangeToPrimaryTarget'' || float || The distance in metres to the AI’s target (i.e., the ship it is trying to shoot). 0 if no target.
|-
| ''laserColor'' || colour || The colour of the ship’s laser.
|-
| ''isHulk'' || bool || True if the ship has been abandoned.
|-
| ''lightsActive'' || bool || True if flashers are turned on, false otherwise.
|-
|}

==== Player ship ====
The player ship has all the properties of [[#Entity|entities]] and [[#Ship|ships]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable player ship properties
! Name !! Type !! Description
|-
| ''massLocked'' || bool || True if the ship is too close to a large object to be able to make a witchspace jump.
|-
| ''atHyperspeed'' || bool || True if the ship is at hyperspeed.
|-
| ''velocityVector'' || vector || The ship’s velocity.
|-
| ''dialForwardShield'' || float || The forward shield level, ranging from 0.0 to 1.0.
|-
| ''dialAftShield'' || float || The aft shield level, ranging from 0.0 to 1.0.
|-
| ''dialMissileStatus'' || int || State of selected missile – 0 for safe/no missile, 1 for active, 2 for locked.
|-
| ''dialFuelScoopStatus'' || int || State of cargo scoop – 0 for no scoop installed, 1 for full hold, 2 for idle with space in hold, 3 for actively scooping.
|-
| ''compassMode'' || int || State of advanced space compass – 0 for no advanced space compass installed, 1 for planet mode, 2 for station mode, 3 for sun mode, 4 for target mode, 5 for any beacon. More may be added in future.
|-
| ''activeMissile'' || int || Which missile slot is currently selected, from 0 to ''dialMaxMissiles'' - 1.
|-
| ''dialMaxMissiles'' || int || The number of missile slots on the ship.
|-
| ''dialIdentEngaged'' || bool || True if ident (targeting) mode is active.
|-
| ''alertCondition'' || int || Current alert condition – 0 for docked, 1 for green, 2 for yellow, 3 for red.
|-
| ''trumbleCount'' || int || Number of trumbles with which the player’s ship is infected.
|-
|}
Additionally, all [[Methods#Querying states|state query scripting methods]] ending with ''_number'' may be used for the player.


[[Category:Oolite]]
[[Category:Oolite scripting]]