GUI Scripting: RenderDef - Revision history

Geep: Add category tag

2022-11-04T17:46:51Z

Add category tag

← Older revision		Revision as of 17:46, 4 November 2022
Line 162:		Line 162:
	===Light Bug, Now Fixed===		===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.		Note bug 4569, discovered by Durandall. Lightcolor and lightorigin were ignored starting in TDM 1.08. Functionality was restored in 2.07.

			{{GUI}}

Geep: /* Additional Properties Specific to RenderDefs */

2022-10-14T16:06:26Z

Additional Properties Specific to RenderDefs

← Older revision		Revision as of 16:06, 14 October 2022
Line 7:		Line 7:

	==Additional Properties Specific to RenderDefs==		==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.		'''®''' = 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, nor appear within event handlers.

	'''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.		'''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.

Geep: /* Compass HUD Example */ Add link to Inventory#Custom_HUDs

2022-08-23T21:22:10Z

Compass HUD Example: Add link to Inventory#Custom_HUDs

← Older revision		Revision as of 21:22, 23 August 2022
Line 107:		Line 107:
	}		}
	...		...
			This "playertools_compass" script object contains additional required functions to manage the display of an item in inventory. For more about this, see [[Inventory#Custom_HUDs]].

	==Anim Example==		==Anim Example==

Geep: /* Complications with RenderDefs */ Camera fov

2022-08-16T22:03:18Z

Complications with RenderDefs: Camera fov

← Older revision		Revision as of 22:03, 16 August 2022
Line 157:		Line 157:
	[https://forums.thedarkmod.com/index.php?/topic/11058-things-that-could-be-improved/&do=findComment&comment=380003 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.)		[https://forums.thedarkmod.com/index.php?/topic/11058-things-that-could-be-improved/&do=findComment&comment=380003 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.)

	It is unfortunate that renderDef is limited to a single light source, and offers no fov/zoom Properties. (The situation is more flexible with the player's view, which can be set with CVar "g_fov ''viewAngle''". In addition, from within DoomScript there are further relevant functions that can be applied to $player1: getFov, startZoom, endZoom, and resetZoom.)		It is unfortunate that renderDef is limited to a single light source, and offers no fov/zoom Properties. The camera has a fixed horizontal field of view of 90 degrees, with vertical appropriately adjusted based on the rect dimensions. (The situation is more flexible with the player's view, which can be set with CVar "g_fov ''viewAngle''". In addition, from within DoomScript there are further relevant functions that can be applied to $player1: getFov, startZoom, endZoom, and resetZoom.)

	===Light Bug, Now Fixed===		===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.		Note bug 4569, discovered by Durandall. Lightcolor and lightorigin were ignored starting in TDM 1.08. Functionality was restored in 2.07.

Geep: /* Complications with RenderDefs */ mention lack of fov/zoom/multi-lights

2022-08-16T15:16:44Z

Complications with RenderDefs: mention lack of fov/zoom/multi-lights

← Older revision		Revision as of 15:16, 16 August 2022
Line 156:		Line 156:

	[https://forums.thedarkmod.com/index.php?/topic/11058-things-that-could-be-improved/&do=findComment&comment=380003 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.)		[https://forums.thedarkmod.com/index.php?/topic/11058-things-that-could-be-improved/&do=findComment&comment=380003 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.)

			It is unfortunate that renderDef is limited to a single light source, and offers no fov/zoom Properties. (The situation is more flexible with the player's view, which can be set with CVar "g_fov ''viewAngle''". In addition, from within DoomScript there are further relevant functions that can be applied to $player1: getFov, startZoom, endZoom, and resetZoom.)

	===Light Bug, Now Fixed===		===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.		Note bug 4569, discovered by Durandall. Lightcolor and lightorigin were ignored starting in TDM 1.08. Functionality was restored in 2.07.

Geep: Add Anim Example, Complications with RenderDefs

2022-08-15T20:51:55Z

Add Anim Example, Complications with RenderDefs

@@ Line 46: / Line 46: @@
 ===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".''
+''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''"====
@@ Line 107: / Line 107: @@
+  }
   ...
 ==Additional Notes==
@@ Line 130: / Line 151: @@
 For a fuller understanding, a good resource is [https://danceswithcode.net/engineeringnotes/rotations_in_3d/rotations_in_3d_part1.html D. Rose, "Rotations in Three-Dimensions: Euler Angles and Rotation Matrices - Part 1", Feb., 2015].
 ===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.

Geep: /* Model "path_to_model_file" */ Add variant compass mention

2022-08-15T18:15:46Z

Model "path_to_model_file": Add variant compass mention

← Older revision		Revision as of 18:15, 15 August 2022
Line 22:		Line 22:
	====Model "''path_to_model_file''"====		====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 (.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"		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'' ®====		====Modelorigin ''vector3of4'' ®====

Geep: /* Render Def Properties – Not Used in TDM Core */

2022-08-15T17:55:04Z

Render Def Properties – Not Used in TDM Core

← Older revision		Revision as of 17:55, 15 August 2022
Line 44:		Line 44:
	viewOffset -10, 0, 6, 1		viewOffset -10, 0, 6, 1

	===~~Render Def~~ Properties – Not Used in TDM Core===		===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".''		''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".''

Geep: /* ModelRotate and Pitch, Yaw, and Roll */

2022-08-15T17:52:14Z

ModelRotate and Pitch, Yaw, and Roll

← Older revision		Revision as of 17:52, 15 August 2022
Line 119:		Line 119:
	# About the x-axis, called "roll". This is "fall over sideways".		# About the x-axis, called "roll". This is "fall over sideways".

	This is described in TDM’s Angles.h thusly:		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.''		''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.''

Geep: create this article

2022-08-15T17:48:35Z

create this article

New page

''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 [[GUI Scripting: Properties in Common | Properties in Common]], only a few are needed, such as the rect and making the background transparent. [[GUI Scripting: User Variables | User variables ]] will probably not be needed, but [[GUI Scripting: GUI:: Parameters | 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"

====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

===Render Def 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".''

====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);
}
...

==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:
# 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.
# 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.
# About the x-axis, called "roll". This is "fall over sideways".

This 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:
# pitch
# yaw
# roll

For a fuller understanding, a good resource is [https://danceswithcode.net/engineeringnotes/rotations_in_3d/rotations_in_3d_part1.html D. Rose, "Rotations in Three-Dimensions: Euler Angles and Rotation Matrices - Part 1", Feb., 2015].

===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.