API Question MATPROP Enumerators and Mesh Material Specification?

Thunder Chicken

Resident Lua Script Rabble-Rouser
Donator
Joined
Mar 22, 2008
Messages
5,847
Reaction score
5,509
Points
188
Location
Massachusetts
It is possible to set mesh material colors by using oapi.set_materialex(hdevmesh, mat_id, MATPROP.<DESCRIPTOR>, color). But I am trying to map the MATPROP specs to what they control in the material definition in the mesh file. Some things are obvious, but some are not, and the documentation text isn't completely clear on some points.

I found the following documentation in the GitHub repositories in Lua syntax, and there is a nearly identical description of MatProp enumerators on page 519 of the Orbiter API reference:

Code:
MATPROP.DIFFUSE Material Diffuse color or Albedo depending on shader used. [.rgba]
MATPROP.AMBIENT Ambient color or Ambien occlusion [.rgb]
MATPROP.SPECULAR Specular color [.rgb] power in [.a]
MATPROP.LIGHT DX7 Style emission (color is added in light that lits the diffuse texture) (i.e. light map) [.rgb]
MATPROP.EMISSION Still in a development currently: output = max(diffuse*light, emission) [.rgb]
MATPROP.REFLECT Reflectivity [.rgb]
MATPROP.SMOOTH Smoothness in [.r] (1 = smooth, 0 = rough)
MATPROP.METAL Metalness in [.r]  (1 = metal, 0 = non-metal)
MATPROP.FRESNEL Fresnel terms for fresnel effect. Used in older 2nd generation shader.
MATPROP.SPECIALFX Heat map effect control variable in [.r] (i.e. average part temperature)

The material specification in the mesh file looks like this:

Code:
MATERIAL Main
0.161 0.216 0.176 1.000
0.438 0.502 0.457 1.000
0.438 0.502 0.457 1.000 0.000
0.000 0.000 0.000 0.000
  • The first line of numbers is the diffuse rgba color, which can be enumerated with MATPROP.DIFFUSE.
  • The second line is the ambient rgba color, which can be enumerated with MATPROP.AMBIENT, though I am not sure the alpha channel is used as the documentation indicates "[rgb]".
  • The third line is specular rgba color, with a reflectivity power. I'm assuming the color can be enumerated with MATPROP.SPECULAR, but the documentation states "Specular color [.rgb] power in [.a]", so I am unsure if it requires an [rgb] color, an [rgba] color, or is actually setting a power level. The method fails if I simply apply a number so I am assuming it must be a color vector of some sort.
  • The fourth line is the emissive rgb color, which is enumerated by MATPROP.LIGHT.
So I am struggling to determine whether the ambient and specular color enumerators are looking for a full rgba color definition, and how the specular power in the material relates to the other enumerators. Is it controlled by MATPROP.REFLECT? The documentation says that needs an [rgb] color. Is the power MATPROP.SMOOTH or METAL? It's not clear from the documentation. Can anyone explain these?
 
AFAIK Ambient is RGB
Spec is RGB+A+power

D3D9Client.pdf says:

Material property
Diffuse
Defines diffuse material color [RGBA]. Texture is modulated with this color. The range for
every property in this section is [0.0 to 1.0] unless otherwise noted.
Ambient
Defines ambient material color [RGB].
Specular
Defines specular material color [RGBP]. The last field is a specular power from [0.0 to 1000.0].
Emissive
Defines emissive material color [RGB].
Reflect
Defines reflection color [RGB] for a metallic (mirror a-like) reflection which intensity is
independent from a viewing angle. This is also used to define minimum reflection offset for a
fresnel reflection. Due to some implementation problems a non-zero value must be entered to
enable fresnel reflections. For a mirror like reflections a typical range is [0.0 to 1.0] and for a
fresnel reflections a typical range is [0.05 to 0.2].
Dissolve
Dissolve is an experimental technique that can be used to create blurry or noisy reflections.
Currently it can be only applied to non-normal mapped surface that has a texture. It would be
possible to use a screen-space coordinates to create a similar effect to a non-textured materials
as well. The first field is the effect scale factor (i.e. particle size). The second field is the effect
strength. If either parameter is zero the effect will be disabled. This property requires dissolve
effect texture.
Fresnel
The first field in fresnel parameters is a power value. A typical range for the power is [2.5 to
4.5]. The power value will effect in a viewing angle dependency of the reflection. The second
field is a multiplier. It will define a maximum reflection intensity when viewed from a shallow
angle. This value must be zero to disable fresnel reflections otherwise a typical range is [0.8 to
0.95].

Advanced Texture Maps
Additional texture maps can be automatically assigned for a mesh simply by placing additional
textures into a texture folder. Additional textures are identified by using an identifier in the end of the
textures name like "dgmk4_1_bump.dds" where "dgmk4_1.dds" is the name of the base texture.
A fully specified texture set could for example consist of these files:
cube.dds <= 'base' texture
cube_bump.dds <= 'advanced texture Bump-map'
cube_spec.dds <= 'advanced texture Specular-map'
cube_emis.dds <= 'advanced texture Emission-map'
cube_refl.dds <= 'advanced texture Reflection-map'
Available identifiers are:
<_norm>
Tangent space normal map and the valid formats are:
<R8G8B8>3-bytes per pixel. Best quality (uncompressed)
<V8U8> 2-bytes per pixel. Good quality (uncompressed)
<DXT1> 1-byte per pixel. Bad quality (compressed)
Note: The configuration of this (_norm) identifier is ignored if a _bump configuration is also
found. However, the _norm configuration is the preferred one that should be used when you have
the choice (see also _bump).
<_spec>
Specular map controls a specular reflection in per pixel basis. Alpha channel is containing a
specular power setting. Value 255 is mapped to maximum matarial defined power and 0 is mapped
to 0.0. Specular map is modulated by specular material color. Valid formats are <R8G8B8A8>,
<DXT3> or <DXT5>.
<_bump>
Bump maps are also supported by the D3D9Client. They are automatically converted into normal
maps during loading of bump maps (see note).
The recommended formats are <A8> and <L8>:
<A8>1-byte per pixel alpha
<L8> 1-byte per pixel luminance
From the not recommended multi-channel textures only the red channel is used;
They are:
<R8B8G8>3-bytes per pixel (only red is used anyway
<DXT1> 1-byte per pixel compressed
<R16F> 2-bytes per pixel (might work, not tested!)
Note: The configuration using the (_bump) identifier will overwrite any _norm configuration in
case both identifiers are found. The _norm configuration is however the one that should be used
when you have the choice (see also _norm).
- 21 -
<_emis>
Currently emission map works more like a light map and the simplified equation is:
pixel_color.rgb = texture.rgb * clamp(emission_map.rgb +
sun_light.rgb + local_lights.rgb)
Alpha channel is ignored therefore the recommended formats are <R8G8B8> or <DXT1>.
The exact implementation would require some discussion with an add-on developers to define the
function for the emission map. An other possibility is:
pixel_color.rgb = texture.rgb * clamp(sun_light.rgb + local_lights.rgb)
+ emission_map.rgb
Of course, the clamp function can be changed to a different kind of color curve manipulation
function to control contrast and lightness.
<_refl>
Reflection map controls material reflectivity and color in a per pixel basis. Fresnel reflection
works independently from a reflection map. However, a zero (black) reflection map value will
mask off the fresnel reflections as well. A non zero value will apply full fresnel reflections for that
pixel. Only [RGB] channels from a texture are used.
<_transl>
Translucence map controls the material translucency on a per pixel basis. The texture behaves
much like a diffuse texture, except that it is illuminated from behind. Illumination is based on the
angle of the sun relative to the surface; if the sun is directly behind the surface, the illumination is
strong, and if the sun is at a low angle but still behind the surface, the illumination is dim. If the
sun begins to illuminate the surface from in front, the translucence effect is no longer visible.
Only [RGB] channels from a texture are used.
<_transm>
Transmittance map controls the amount of light that passes through a translucent material without
being diffused. The effect is very similar to a specular reflection, except that it simulates the bright
spot on a semi-transparent material that is directly between the sun and the observer.
The [RGBA] channels from a texture are used. The RGB channels providec olor and brightness,
while the alpha channel changes the size of the bright spot. This is analogous to how the specular
map is used.
Note, that not all objects support all advanced texture maps:
Type Identifier Vessel Base Planetary Surface
Bump-map _bump supported supported not supported
Specular-map _spec supported supported not supported
Emission-map _emis supported supported not supported
Reflection-map _refl supportednot supported not supported
Translucence-map _transl supportednot supported not supported
Transmittance-map _transm supportednot supported not supported

Hope this helps
So for a spec material you only need RGB+power
Note I have seen meshes with a second spec power variable? I have never seen any Orbiter documentation on this but in the 3D world spec is represented as a bell curve and the second variable is the width, so it would make sense.

Is the power MATPROP.SMOOTH
I don't know MATPROP but I think this would be the second power value, but there should also be Roughness and Metal somewhere?
 
Last edited:
Where is this document located?
comes with the Orb2016 D3D9 download ( but I think I've already posted all the relevant bits, but there is another doc in orbitersdk that has a workflow chart that might be interesting).
What is the table key for power in Lua Script?
No idea, sorry:)
Doesn't the alpha channel need to be specified?
MATERIAL Main
0.161 0.216 0.176 1.000
0.438 0.502 0.457 1.000
0.438 0.502 0.457 1.000 1.000
0.000 0.000 0.000 0.000

looks correct, define alpha for all, and should be 1 ((except emmis.) unless the diffuse material is transparent), this is how the .msh works, maybe Lua ignores the alpha?
 
comes with the Orb2016 D3D9 download ( but I think I've already posted all the relevant bits, but there is another doc in orbitersdk that has a workflow chart that might be interesting).

No idea, sorry:)

MATERIAL Main
0.161 0.216 0.176 1.000
0.438 0.502 0.457 1.000
0.438 0.502 0.457 1.000 1.000
0.000 0.000 0.000 0.000

looks correct, define alpha for all, and should be 1 ((except emmis.) unless the diffuse material is transparent), this is how the .msh works, maybe Lua ignores the alpha?
Lua does pretty much what the C++ API does with the MATPROP/MatProp enumerators. I'm just trying to get definitive information on what those enumerators control.
 
comes with the Orb2016 D3D9 download ( but I think I've already posted all the relevant bits, but there is another doc in orbitersdk that has a workflow chart that might be interesting).
I really don't see the D3D9Client.pdf and other D3D9 documentation in the Orbiter 2024 installation. Are they included (be a part) into some other document?
 
I really don't see the D3D9Client.pdf and other D3D9 documentation in the Orbiter 2024 installation. Are they included (be a part) into some other document?
The flowchart he is referring to is in the Orbiter Developer Manual, but there is no D3D9 information in that manual. D3D9Client.pdf isn't available in Orbiter 2024.
 
Back
Top