GUI Scripting: RenderDef

This page is part of a series. See GUI Scripting Language for overview.

Introduction

A renderDef allows dynamic projection of a 3D model, in its own separate world, onto a 2D surface. The orientation of the model can be dynamically and programmatically controlled. The only use of a renderDef in the core is for the compass that can be shown in the HUD, and whose orientation changes automatically as the player faces in different directions.

Properties Shared by All GuiDef Types

Of the Properties in Common, only a few are needed, such as the rect and making the background transparent. User variables will probably not be needed, but GUI:: Parameters will be vital to control the orientation of the model from a script.

Additional Properties Specific to RenderDefs

® = A property known as a "register", that can be altered at runtime by binding it to a GUI:: parameter, or in a "set" or "transition" script command. Other properties cannot be so altered.

Vector3of4 = A list of 4 floats (comma-separated in a Property declaration), but only the first 3 elements matter. This is a workaround for lack of vector3 parsing support by GUI script. By convention, use "0" or "1" as fourth element.

RenderDef Properties – Used in TDM Core

Lightcolor vector3of4 ®

Color of the light. Elements in range 0 to 1. This is RGB, not RGBA. Default is 1,1,1,1 (white).

lightColor  1, 1, 1, 1

Lightorigin vector3of4 ®

Position of the light. Default is -128,0,0,1.

lightOrigin  -50, 0, 50, 0

Model "path_to_model_file"

Model (.ase or .lwo file, not model def) to render. For simple models, this is as a func_static entity.

model "models/darkmod/player_equipment/compass.ase" // Standard TDM
model "models/erh/submarine/er_sub_compass.ase" // Variant compass in "Seed of Lodestar" beta FM by ERH+

Modelorigin vector3of4 ®

Position of the model. Default 0,0,0,0.

modelOrigin  0, 0, 0, 1

Modelrotate vector3of4 ®

Rotation by Euler angles (-180 to 180 or equivalently 0 to 360 degrees). Vector elements are respectively pitch, yaw, and roll. See "Additional Notes" below for more. Default 0,0,0,0.

modelRotate  ("gui::modelPitch"), ("gui::modelYaw"), ("gui::modelRoll"), 1 // controlled by playertools script; see example below.

Needsrender bool

Dirty flag. If 1 (true), something changed so the scene must be rendered again. Default is 0 (false).

needsRender 1

Noshadows bool

If 1 (true), prevents the model from casting a shadow, just like the familiar spawnarg on any entity. Default is 1 (true).

noshadows 1

Viewoffset vector3of4 ®

Position of the camera. Default -128,0,0,1

viewOffset  -10, 0, 6, 1

RenderDef Properties – Not Used in TDM Core

These appear to be intended for Articulated Figure models. Specifically, given the Animclass name, find the entityDef. Then look for its "model" specification. From that, find the modelDef, and within that, the md5animation matching the "anim_name". For more, see the "Anim Example" below.

Anim "anim_name"

Animation to play.

Animclass "class_name"

entityDef to grab the animation from.

Compass HUD Example

The tdm_gui01.pk4\guis\playertools\compass.gui by Drumple and greebo:

windowDef Desktop {
    rect       500, 290, 140, 180
    backcolor  0 ,0 ,0 ,0 
    visible    "gui::CompassVisible"
    nocursor   1

    renderDef compassModel
    {
        rect         0, 0, 140, 180
        visible      1
        backcolor    0, 0, 0, 0
        model        "models/darkmod/player_equipment/compass.ase"
        needsRender  1
        modelRotate  ("gui::modelPitch"), ("gui::modelYaw"), ("gui::modelRoll"), 1
        modelOrigin  0, 0, 0, 1
        viewOffset   -10, 0, 6, 1
        lightOrigin  -50, 0, 50, 0
        lightColor   1, 1, 1, 1
        noshadows    1
    }
} // Desktop

Then, in tdm_playertools.script, there is code that creates an overlay for the compass in the HUD and, when the compass is visible, updates its image every frame. The latter, which takes the player’s orientation and calculates the GUI Parameters "modelPitch", "modelYaw", and "modelRoll", is:

...
#define COMPASS_MIN_PITCH -75
#define COMPASS_MAX_PITCH 40

void playertools_compass::updateCompass(entity userEntity) // userEntity is the player
{
   _playerAngles = userEntity.getViewAngles();

    float yaw = _playerAngles_y - 90;

    // Clamp the pitch to [COMPASS_MIN_PITCH .. COMPASS_MAX_PITCH]
    float playerPitchClamped = _playerAngles_x;

    if (playerPitchClamped > 0) {
       playerPitchClamped = COMPASS_MAX_PITCH * playerPitchClamped/90;
    }
    else {
        playerPitchClamped = COMPASS_MIN_PITCH * -playerPitchClamped/90;
    }

    float modelPitch = playerPitchClamped * sys.sin(yaw);
    float modelRoll = playerPitchClamped * sys.cos(yaw);

    userEntity.setGuiFloat(_overlayHandle, "modelYaw", -_playerAngles_y);
    userEntity.setGuiFloat(_overlayHandle, "modelPitch", modelPitch);
    userEntity.setGuiFloat(_overlayHandle, "modelRoll", modelRoll);
}
...

Anim Example

Back in 2006, when the early form of TDM’s main menu system was being designed, various ideas where considered for a side area next to the menu parchment. This area should have images of characters (guard, priest, haunt, noble) fade in and out, blended into a swirling brown background. One idea that drumple tested was using a renderDef of a representative animated 3D AI model:

renderDef ModelRender {
   rect         0,10, 320, 400
   visible      1
   backcolor    0, 0, 0, 0
   bordercolor  1,1,1,1
   bordersize   0
   model        "models/md5/chars/guards/elite_citywatch/elitecitywatchmesh.md5mesh"
   anim         "idle"
   animClass    "darkmod_citywatch_elite"
   needsRender  1
   modelRotate  10, 180, 0, 0
   modelOrigin  0, 0, 0, 0
   viewOffset   -60, 0, 50, 0
   lightOrigin  -100, 50, 0, 0
   lightColor   1, 1, 1, 1
   notime       1
}

Presumably there was a parent windowDef with the brown background. Drumple felt the renderDef needed further property adjustments, to minimize skewing due to touchy fisheye perspective. Nevertheless, Gildoran liked the results, finding that the model - blended into its background - evoked the moving newspaper pictures from Harry Potter movies. But Springheel thought it inferior to the illustration look possible with pre-rendered shots. The latter was adopted.

Additional Notes

ModelRotate and Pitch, Yaw, and Roll

Think in terms of an airplane model, with origin at its center of gravity, and its own relative axes passing through the origin. Namely:

• x axis extends along the length of the plane. So forwards/backwards.
• y axis is perpendicular to that and right/left (wing-aligned).
• z axis is perpendicular to those axes and up/down (ceiling/floor aligned)

When the plane is on ground and facing north (compass angle 0), its axes are aligned with the world coordinates. Then, to describe a different orientation, 3 consecutive rotations about each of the plane's axes is done. The order that these are applied very much matters, and is:

1. About the z-axis, called "yaw". (Other terms are pan or azimuth or heading). After this rotation, the plane's x/y axes are usually no longer aligned with the world x/y axes.
2. About the y-axis, called "pitch". (Other terms are elevation or tilt). After this rotation, the plane's x/y/z axes are usually no longer aligned with the world x/y/z axes.
3. About the x-axis, called "roll". This is "fall over sideways".

This order of rotations is described in TDM’s Angles.h thusly:

idAngles uses the "yaw, pitch, roll" convention, in which the yaw rotation occurs first, then pitch occurs relative to the yawed axes, and finally roll occurs relative to the yawed and pitched axes. Also known as the "zyx" convention.

Unfortunately, the vector elements for idAngles and so ModelRotate must be entered in a different order:

1. pitch
2. yaw
3. roll

For a fuller understanding, a good resource is D. Rose, "Rotations in Three-Dimensions: Euler Angles and Rotation Matrices - Part 1", Feb., 2015.

Complications with RenderDefs

Springheel in 2007 explored using renderDefs to represent purchasable items in the store in 3D. The interest was to support mappers creating custom items with new models. But each model would need to come with its own set of renderDef Properties (e.g., modelOrigin, viewOffset, etc.). Otherwise, if you just tried to use generic settings, models would appear too small, too large (and clipped), badly skewed, and so on. Mappers could have difficulty understanding how to come up with good Property values. And maybe low-poly models would be needed to avoid renderDef lagginess. In the end, it was decided that having mappers provide 2D static image files - which they would probably need anyway for inventory icons - was easier.

A 2015 discussion considered whether, as an improvement to realism, a shouldered corpse could be a ragdoll. One approach would be use a renderDef to create an overlay (e.g., of the legs) within the main field of view. Vanished One recalled that one reason TDM has an icon-based HUD is that you can't specify a skin for display in a renderDef. (Drumple’s concern about renderDef fisheye distortion, mentioned above, was also noted. Other posts expressed concerns about point-of-view conflicts when turning with intrusive legs.)

Light Bug, Now Fixed

Note bug 4569, discovered by Durandall. Lightcolor and lightorigin were ignored starting in TDM 1.08. Functionality was restored in 2.07.