Materials in Oolite
- This section applies to Oolite 1.69 and later.
Traditionally, the surface appearance of ships in Oolite has been defined entirely by textures specified in the ship’s model file and the smooth attribute. Test release 1.67 added support for shaders, and test release 1.69 expands this to a more flexible material model. Under the new model, the texture file names in model files have been repurposed as material keys. A material key specifies an entry in the ship’s material dictionary, specified in the ship’s shipdata.plist entry. For backwards compatibility, if no material of a given name is found, a material is generated using the material key as a diffuse texture name – providing the same functionality as previous versions of Oolite.
Contents
The materials and shaders dictionary
The material dictionary is actually specified as two separate dictionaries in the shipdata.plist entry. The first is called materials, the second shaders. If shader support is available and enabled, the entries in shaders are used in preference to those in materials. Otherwise, shaders is ignored. The entries in the two dictionaries take exactly the same form, however; it is possible to specify a shader in the materials dictionary, and it will simply be ignored if shader support is not available. The rest of this article shall refer to the merged materials and shaders dictionaries as “the material dictionary”.
Material attributes dictionaries
The material dictionary is a property list dictionary whose keys are material keys as defined above, and whose values are material attribute dictionaries. Currently-supported material attribute dictionary keys are listed here; “texture specifier” and similar are defined below.
| Name | Type | Description |
|---|---|---|
| ambient | colour specifier | The ambient colour of the entity, that is, the colour reflected evenly in all directions by starlight. By default, this is the same as diffuse. |
| diffuse | colour specifier | Overall diffuse colour of the entity; that is, the colour reflected in a “non-shiny” way on the sunlit side of the entity. If both diffuse and diffuse_map are specified, the texture is “dyed” with this colour. Default: white (1.0, 1.0, 1.0, 1.0). |
| diffuse_map | texture specifier | A texture specifying the basic colour of the material. This is a “normal” texture, the same as you get without a material dictionary. If not specified, the material key will be used. To specify no texture, use an empty string for diffuse_map. Ignored when using shaders. |
| emission | colour specifier | The emitted (glow) colour of the material. Default: black (0.0, 0.0, 0.0, 1.0). |
| shininess | integer | The “tightness” of specular reflect, ranging from 0 to 128. 0 means no specular highlight. Default: 0, may change in future. |
| specular | colour specifier | The specular (shiny reflection) colour of the material. This is ignored if shininess is not 1 or more. Default: black (0.0, 0.0, 0.0, 1.0), may change in future. |
| textures | array of texture specifiers | Textures to use in shader program. |
The following attributes are only supported if shader support is active:
| Name | Type | Description |
|---|---|---|
| fragment_shader | file name | name of GLSL fragment program to use. |
| textures | array of texture specifiers | Textures to use in shader program. |
| uniforms | dictionary of uniform variable specifiers | uniform variables to use in shader program. See Shaders in Oolite: uniforms. |
| vertex_shader | file name | name of GLSL vertex program to use. |
Colour specifiers
Colour specifiers are used to declare colours in material attribute dictionaries, and in other contexts such as lasers in shipdata.plist. Colour specifiers take any of several forms:
Named colours
The simplest form of colour specifier is a string containing a colour name. The following names are supported:
| Name | RGBA value |
|---|---|
| blackColor | 0, 0, 0, 1.0 |
| darkGrayColor | 1/3, 1/3, 1/3, 1.0 |
| lightGrayColor | 1/6, 1/6, 1/6, 1.0 |
| whiteColor | 1, 1, 1, 1 |
| grayColor | 1/2, 1/2, 1/2, 1 |
| redColor | 1, 0, 0, 1 |
| greenColor | 0, 1, 0, 1 |
| blueColor | 0, 0, 1, 1 |
| cyanColor | 0, 1, 1, 1 |
| yellowColor | 1, 1, 0, 1 |
| magentaColor | 1, 0, 1, 1 |
| orangeColor | 1, 1/2, 0, 1 |
| purpleColor | 1/2, 0, 1/2, 1 |
| brownColor | 0.6, 0.4, 0.2, 1 |
| clearColor | 0, 0, 0, 0 |
RGBA tuples
Colours may also be specified in RGB or RGBA (red, green, blue, alpha [transparency]). RGB or RGBA tuples may be specified as arrays or as strings separated by spaces. The values may range from 0 to 1 or 0 to 255. (If no value is greater than 1, 0–1 is assumed, otherwise 0–255.) Examples:
<string>1 1 0</string> <!-- yellow --><string>0 128 0 128</string> <!-- medium green at 50% opacity --><array><real>1</real> <real>0</real> <real>0</real></array> <!-- red -->
RGBA dictionaries
Just in case you’re unsure of the order the RGB[A] components come in, you can use a dictionary:
<dict>
<key>blue</key> <real>0.8</real>
<key>green</key> <real>0.8</real>
</dict>
Accepted keys are red, green, blue and alpha (or opacity), all optional (default: 0.0 for red, green and blue, 1.0 for alpha).
HSBA dictionaries
But wait, there’s more! Colours may also be specified as dictionaries in the HSB colour space. Accepted keys are hue' (hue angle in degrees, required), saturation, brightness (or value) and alpha (or opacity). The default for the optional keys is 1.0.
<dict>
<!-- Pale magenta -->
<key>hue</key> <real>300</real>
<key>saturation</key> <real>0.3</real>
</dict>
