Skip to content

Draw3D

Info

Dependencies:
- PermMem
- HookEngine
Implementation:
Draw3D.d on GitHub

This package allows you to draw various shapes (such as lines or bounding boxes) in three-dimensional space. This makes debugging visualizations of coordinates in the world possible.

Initialization

Initialize with LeGo_Draw3D flag. 

1
LeGo_Init(LeGo_Draw3D);

Functions

Line

DrawLine

DrawLine

Creates and draws a new line and returns its handle. 

1
func int DrawLine(var int startPosPtr, var int endPosPtr, var int color)
Parameters
  • var int startPosPtr
    Pointer to the float array with world coordinates of the starting point of the line
  • var int endPosPtr
    Pointer to the float array with world coordinates of the ending point of the line
  • var int color
    Color of the line as zCOLOR

Return value

The function returns a new PermMem handle to the line.

DrawLine3

DrawLine3

DrawLine, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func int DrawLine3(var int x1, var int y1, var int z1,var int x2, var int y2, var int z2,var int color)
Parameters
  • var int x1, y1, z1
    X, Y, and Z coordinates of the starting point of the line
  • var int x2, y2, z2
    X, Y, and Z coordinates of the ending point of the line
  • var int color
    Color of the line as zCOLOR

Return value

The function returns a new PermMem handle to the line.

DrawLineAddr

DrawLineAddr

DrawLine, but with the address of a line as parameter. 

1
func int DrawLineAddr(var int linePtr, var int color)
Parameters
  • var int linePtr
    Pointer to the float array array with six values (startAndEndPos[6])
  • var int color
    Color of the line as zCOLOR

Return value

The function returns a new PermMem handle to the line.

UpdateLine

UpdateLine

Changes the coordinates of a specific line. 

1
func void UpdateLine(var int hndl, var int startPosPtr, var int endPosPtr)
Parameters
  • var int hndl
    Handle returned from DrawLine
  • var int startPosPtr
    Pointer to an integer float array with world coordinates of the starting point of the line
  • var int endPosPtr
    Pointer to an integer float array with world coordinates of the ending point of the line

UpdateLine3

UpdateLine3

UpdateLine, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func void UpdateLine3(var int hndl,var int x1, var int y1, var int z1,var int x2, var int y2, var int z2)
Parameters
  • var int hndl
    Handle returned from DrawLine
  • var int x1, y1, z1
    X, Y, and Z coordinates of the starting point of the line
  • var int x2, y2, z2
    X, Y, and Z coordinates of the ending point of the line

UpdateLineAddr

UpdateLineAddr

UpdateLine, but with the address of a line as parameter. 

1
func void UpdateLineAddr(var int hndl, var int linePtr)
Parameters
  • var int hndl
    Handle returned from DrawLine
  • var int linePtr
    Pointer to an integer float array with six values (startAndEndPos[6])

SetLineColor

SetLineColor

Changes the color of a specific line. 

1
func void SetLineColor(var int hndl, var int color)
Parameters
  • var int hndl
    Handle returned from DrawLine
  • var int color
    New color of the line as zCOLOR

EraseLine

EraseLine

Deletes a line from the world and the handle. 

1
func void EraseLine(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawLine

LineVisible

LineVisible

Returns whether a line is visible. 

1
func int LineVisible(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawLine

Return value

The function returns TRUE if the line is visible/displayed. FALSE is returned otherwise.

ShowLine

ShowLine

Displays the line. 

1
func void ShowLine(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawLine

HideLine

HideLine

Hides the line. 

1
func void HideLine(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawLine

ToggleLine

ToggleLine

Changes the visibility of a line. If displayed - hide, if hidden - display. 

1
func void ToggleLine(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawLine

Sphere

DrawSphere

DrawSphere

Creates and draws a new sphere (visualized as a circle) and returns its handle. 

1
func int DrawSphere(var int centerPosPtr, var int radius, var int color)
Parameters
  • var int centerPosPtr
    Pointer to an integer float array with world coordinates of the sphere's center (centerPos[3])
  • var int radius
    Radius of the sphere as an integer float
  • var int color
    Color of the sphere as zCOLOR

Return value

The function returns a new PermMem handle to the sphere.

DrawSphere3

DrawSphere3

DrawSphere, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func int DrawSphere3(var int x1, var int y1, var int z1, var int radius, var int color)
Parameters
  • var int x1, y1, z1
    World coordinates of the sphere's center
  • var int radius
    Radius of the sphere as an integer float
  • var int color
    Color of the sphere as zCOLOR

Return value

The function returns a new PermMem handle to the sphere.

DrawSphereAddr

DrawSphereAddr

DrawSphere, but with the address of a sphere as a parameter. 

1
func int DrawSphereAddr(var int spherePtr, var int color)
Parameters
  • var int spherePtr
    Pointer to a zTBSphere3D structure
  • var int color
    Color of the sphere as zCOLOR

Return value

The function returns a new PermMem handle to the sphere.

UpdateSphere

UpdateSphere

Changes the coordinates and/or size of an existing sphere. 

1
func void UpdateSphere(var int hndl, var int centerPosPtr, var int radius)
Parameters
  • var int hndl
    Handle returned from DrawSphere
  • var int centerPosPtr
    Pointer to an integer float array with world coordinates of the sphere's center (centerPos[3])
  • var int radius
    Radius of the sphere as an integer float

UpdateSphere3

UpdateSphere3

UpdateSphere, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func void UpdateSphere3(var int hndl, var int x1, var int y1, var int z1, var int radius)
Parameters
  • var int hndl
    Handle returned from DrawSphere
  • var int x1, y1, z1
    World coordinates of the sphere's center
  • var int radius
    Radius of the sphere as an integer float

UpdateSphereAddr

UpdateSphereAddr

UpdateSphere, but with the address of a sphere as a parameter. 

1
func void UpdateSphereAddr(var int hndl, var int spherePtr)
Parameters
  • var int hndl
    Handle returned from DrawSphere
  • var int spherePtr
    Pointer to a zTBSphere3D structure

SetSphereColor

SetSphereColor

Changes the color of a specific sphere. 

1
func void SetSphereColor(var int hndl, var int color)
Parameters
  • var int hndl
    Handle returned from DrawSphere
  • var int color
    New color of the sphere as zCOLOR

EraseSphere

EraseSphere

Deletes a sphere from the world and its handle. 

1
func void EraseSphere(var int hndl)
Parameters

SphereVisible

SphereVisible

Returns whether a sphere is visible. 

1
func int SphereVisible(var int hndl)
Parameters

Return value

The function returns TRUE if the sphere is visible/displayed. FALSE is returned otherwise.

ShowSphere

ShowSphere

Displays the sphere. 

1
func void ShowSphere(var int hndl)
Parameters

HideSphere

HideSphere

Hides the sphere. 

1
func void HideSphere(var int hndl)
Parameters

ToggleSphere

ToggleSphere

Changes the visibility of a sphere. If displayed - hide, if hidden - display. 

1
func void ToggleSphere(var int hndl)
Parameters

Bounding Box

DrawBBox

DrawBBox

Creates and draws a new bounding box and returns its handle. 

1
func int DrawBBox(var int startPosPtr, var int endPosPtr, var int color)
Parameters
  • var int startPosPtr
    Pointer to an integer float array with world coordinates of the bounding box's first point (startPos[3])
  • var int endPosPtr
    Pointer to an integer float array with world coordinates of the bounding box's second point (endPos[3])
  • var int color
    Color of the bounding box as zCOLOR

Return value

The function returns a new PermMem handle to the bounding box.

DrawBBox3

DrawBBox3

DrawBBox, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func int DrawBBox3(var int x1, var int y1, var int z1, var int x2, var int y2, var int z2, var int color)
Parameters
  • var int x1, y1, z1
    World coordinates of the bounding box's first point
  • var int x2, y2, z2
    World coordinates of the bounding box's second point
  • var int color
    Color of the bounding box as zCOLOR

Return value

The function returns a new PermMem handle to the bounding box.

DrawBBoxAddr

DrawBBoxAddr

DrawBBox, but with the address of a bounding box as a parameter. 

1
func int DrawBBoxAddr(var int bboxPtr, var int color)
Parameters
  • var int bboxPtr
    Pointer to an integer float array with six values (startAndEndPos[6])
  • var int color
    Color of the bounding box as zCOLOR

Return value

The function returns a new PermMem handle to the bounding box.

UpdateBBox

UpdateBBox

Changes the coordinates of an existing bounding box. 

1
func void UpdateBBox(var int hndl, var int startPosPtr, var int endPosPtr)
Parameters
  • var int hndl
    Handle returned from DrawBBox
  • var int startPosPtr
    Pointer to an integer float array with world coordinates of the bounding box's first point (startPos[3])
  • var int endPosPtr
    Pointer to an integer float array with world coordinates of the bounding box's second point (endPos[3])

UpdateBBox3

UpdateBBox3

UpdateBBox, but with world coordinates as parameters, instead of zVEC3 pointers. 

1
func void UpdateBBox3(var int hndl, var int x1, var int y1, var int z1, var int x2, var int y2, var int z2)
Parameters
  • var int hndl
    Handle returned from DrawBBox
  • var int x1, y1, z1
    World coordinates of the bounding box's first point
  • var int x2, y2, z2
    World coordinates of the bounding box's second point

UpdateBBoxAddr

UpdateBBoxAddr

UpdateBBox, but with the address of a bounding box as a parameter. 

1
func void UpdateBBoxAddr(var int hndl, var int bboxPtr)
Parameters
  • var int hndl
    Handle returned from DrawBBox
  • var int bboxPtr
    Pointer to an integer float array with six values (startAndEndPos[6])

SetBBoxColor

SetBBoxColor

Changes the color of a specific bounding box. 

1
func void SetBBoxColor(var int hndl, var int color)
Parameters
  • var int hndl
    Handle returned from DrawBBox
  • var int color
    New color of the bounding box as zCOLOR

EraseBBox

EraseBBox

Deletes a bounding box from the world and its handle. 

1
func void EraseBBox(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawBBox

BBoxVisible

BBoxVisible

Returns whether a bounding box is visible. 

1
func int BBoxVisible(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawBBox

Return value

The function returns TRUE if the bounding box is visible/displayed. FALSE is returned otherwise.

ShowBBox

ShowBBox

Displays the bounding box. 

1
func void ShowBBox(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawBBox

HideBBox

HideBBox

Hides the bounding box. 

1
func void HideBBox(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawBBox

ToggleBBox

ToggleBBox

Changes the visibility of a bounding box. If displayed - hide, if hidden - display. 

1
func void ToggleBBox(var int hndl)
Parameters
  • var int hndl
    Handle returned from DrawBBox

Oriented Bounding Box

DrawOBBoxAddr

DrawOBBoxAddr

Creates and draws a new oriented bounding box based on the address of an oriented bounding box and returns its handle. 

1
func int DrawOBBoxAddr(var int oBBoxPtr, var int color)
Parameters
  • var int oBBoxPtr
    Pointer to a zCOBBox3D structure
  • var int color
    Color of the oriented bounding box as zCOLOR

Return value

The function returns a new PermMem handle to the oriented bounding box.

UpdateOBBoxAddr

UpdateOBBoxAddr

Changes the coordinates and orientation of an existing oriented bounding box. 

1
func void UpdateOBBoxAddr(var int hndl, var int oBBoxPtr)
Parameters
  • var int hndl
    Handle returned from DrawOBBoxAddr
  • var int oBBoxPtr
    Pointer to a zCOBBox3D structure

SetOBBoxColor

SetOBBoxColor

Changes the color of a specific oriented bounding box. 

1
func void SetOBBoxColor(var int hndl, var int color)
Parameters
  • var int hndl
    Handle returned from DrawOBBoxAddr
  • var int color
    New color of the oriented bounding box as zCOLOR

EraseOBBox

EraseOBBox

Deletes an oriented bounding box from the world and its handle. 

1
func void EraseOBBox(var int hndl)
Parameters

OBBoxVisible

OBBoxVisible

Returns whether an oriented bounding box is visible. 

1
func int OBBoxVisible(var int hndl)
Parameters

Return value

The function returns TRUE if the oriented bounding box is visible/displayed. FALSE is returned otherwise.

ShowOBBox

ShowOBBox

Displays the oriented bounding box. 

1
func void ShowOBBox(var int hndl)
Parameters

HideOBBox

HideOBBox

Hides the oriented bounding box. 

1
func void HideOBBox(var int hndl)
Parameters

ToggleOBBox

ToggleOBBox

Changes the visibility of an oriented bounding box. If displayed - hide, if hidden - display. 

1
func void ToggleOBBox(var int hndl)
Parameters

EraseAll

EraseAll

Deletes all draw elements and their handles from the world. 

1
func void EraseAll()

Examples

World coordinates are not particularly informative. This package aims to help and allows visualizing world coordinates in the form of lines, spheres (as circles), bounding boxes, and oriented bounding boxes in three-dimensional space.

Visualizing Straight Line to an NPC

To draw a line between two NPCs, you only need the coordinates of the two NPCs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
func void Example_1() {
    var zCVob her; her = Hlp_GetNpc(hero);
    var int point1[3];
    point1[0] = her.trafoObjToWorld[3];
    point1[1] = her.trafoObjToWorld[7];
    point1[2] = her.trafoObjToWorld[11];

    var zCVob oth; oth = Hlp_GetNpc(PC_ThiefOW);
    var int point2[3];
    point2[0] = oth.trafoObjToWorld[3];
    point2[1] = oth.trafoObjToWorld[7];
    point2[2] = oth.trafoObjToWorld[11];

    var int hndl;

    if (!Hlp_IsValidHandle(hndl)) {
        hndl = DrawLine(_@(point1), _@(point2), zCOLOR_GREEN);
    } else {
        UpdateLine(hndl, _@(point1), _@(point2));
    };
};

This function can now be called continuously using FrameFunction to continuously adjust the straight line according to the positions of the characters.

1
FF_Apply(Example_1);

Alternatively, you can write the function as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
func void Example_1() {
    var zCVob her; her = Hlp_GetNpc(hero);
    var zCVob oth; oth = Hlp_GetNpc(PC_ThiefOW);

    var int hndl;

    if (!Hlp_IsValidHandle(hndl)) {
        hndl = DrawLine3(her.trafoObjToWorld[3], her.trafoObjToWorld[7], her.trafoObjToWorld[11],
                         oth.trafoObjToWorld[3], oth.trafoObjToWorld[7], oth.trafoObjToWorld[11],
                         zCOLOR_GREEN);
    } else {
        UpdateLine3(hndl, her.trafoObjToWorld[3], her.trafoObjToWorld[7], her.trafoObjToWorld[11],
                          oth.trafoObjToWorld[3], oth.trafoObjToWorld[7], oth.trafoObjToWorld[11]);
    };
};

Visualizing a Distance of 5 Meters

It becomes more interesting when dealing with "abstract" coordinates. For instance, you can visualize a "safety distance" around the player using a bounding box or a sphere, to check AI reactions at certain distances.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
//*******************
//   Bounding Box
//*******************
func void Example_2() {
    var zCVob her; her = Hlp_GetNpc(hero);

    // Safety distance around the player (5 meters)
    var int distance; distance = mkf(500);

    // Lower corner of the bounding box
    var int point1[3];
    point1[0] = subf(her.trafoObjToWorld[3],  distance);
    point1[1] = subf(her.trafoObjToWorld[7],  distance);
    point1[2] = subf(her.trafoObjToWorld[11], distance);

    // Upper corner of the bounding box (diagonally opposite)
    var int point2[3];
    point2[0] = addf(her.trafoObjToWorld[3],  distance);
    point2[1] = addf(her.trafoObjToWorld[7],  distance);
    point2[2] = addf(her.trafoObjToWorld[11], distance);

    var int hndl;

    if (!Hlp_IsValidHandle(hndl)) {
        hndl = DrawBBox(_@(point1), _@(point2), zCOLOR_BLUE);
    } else {
        UpdateBBox(hndl, _@(point1), _@(point2));
    };
};

To draw a sphere with a radius of 5 meters centered at a specific point, you only need the coordinates of the sphere's center.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
//*******************
//      Sphere
//*******************
func void Example_2() {
    var zCVob her; her = Hlp_GetNpc(hero);
    var int centerPoint[3];
    centerPoint[0] = her.trafoObjToWorld[3];
    centerPoint[1] = her.trafoObjToWorld[7];
    centerPoint[2] = her.trafoObjToWorld[11];

    var int hndl;

    if (!Hlp_IsValidHandle(hndl)) {
        hndl = DrawSphere(_@(centerPoint), 500, zCOLOR_BLUE);
    } else {
        UpdateSphere(hndl, _@(centerPoint), 500);
    };
};

Similarly, you could continuously update the bounding box/sphere using a FrameFunction.

Changing Color or Hiding/Deleting Draw Elements

If you want to visualize an AI reaction, for example, you can change the color. Color values can be created using the RGBA function based on RGB values.

1
2
3
4
5
6
func void ObserveIntruder(var int hndl, var C_NPC oth) {
    if (Npc_HasDetectedNpc(oth, hero)) {
        // Color is now red, position and size of the bounding box remain unchanged
        SetBBoxColor(hndl, zCOLOR_RED); // zCOLOR_RED == RGBA(255, 0, 0, 255)
    };
};

Draw elements can also be easily hidden or completely deleted.

1
2
3
4
5
6
7
8
func void CheckDialog(var int hndl) {
    if (!InfoManager_HasFinished()) {
        // Hide bounding box during dialogs
        HideBBox(hndl);

        // EraseBBox(hndl); // Or delete including the handle
    };
};