Kaim::ScopedDisplayList Class Reference

Kaim::ScopedDisplayList Class Reference

#include <displaylist.h>

Class Description

ScopedDisplayList is used to push text, lines or shapes for rendering in the NavigationLab e.g.

{
ScopedDisplayList displayList(GetWorld());
displayList->InitSingleFrameLifespan("MyDisplayList", "MyGroupOfDisplayLists");
DisplayShapeColor color;
color.SetOnlyLineColor(Kaim::VisualColor::Red);
displayList->PushText(m_head, Kaim::VisualColor::Red, "Error");
displayList->PushPoint(m_position, color);
} // Here the ScopedDisplayList is destroyed and committed to be sent to the NavigationLab and rendered.

In order to be able to easily find, sort and control ScopedDisplayList in the UI of the NavigationLab:

  • a name must be provided to be able to control manually the rendering of a ScopedDisplayList, so it will serve as a label for a check box inside the NavigationLab UI
  • a group identifier must be provided, it can be either a string or a WorldElement's VisualDebugId but it can't be both, if by mistake both would be provided the string will be ignored
    • If a WorldElement Id is given, the rendering of the displayList in the NavigationLab is configured within the element's display widget. This allows for example to render some bot custom information only for a selected Bot.
    • If it is a string, ScopedDisplayLists sharing this string will use it as a name for the display widget in the NavigationLab where all these ScopedDiaplyLists will be gathered.

In case of several ScopedDisplayList were sent with the same name and group identifier in the same frame, they will be controlled all together by the same widget labeled by their common name inside their common group widget in the NavigationLab UI.

ScopedDisplayList can per frame, i.e. the ScopedDisplayList is sent once and it is rendered only for the frame at which it is sent.

But lifespan of rendering can be controlled by providing a unique identifier for the ScopedDisplayList.

This identifier must be unique amongst all ScopedDisplayList, DisplayListManager::GenerateDisplayListId() must be used to get such ids.

So, instead of sending a ScopedDisplayList each frame to see it over several frame whereas its content doesn't change, the ScopedDisplayList can be sent only when its content should change, thus a newly received ScopedDisplayList with an id will replace a previously received ScopedDisplayList and the end of the ScopedDisplayList can be triggered whenever you want.

{
class MyObject
{
public:
Kaim::World* m_world
KyUInt32 m_displayListId;
MyObject(Kaim::World* world)
: m_world(world)
, m_displayListId(KyUInt32MAXVal)
{}
~MyObject()
{
// destroy the ScopedDisplayList into the NavigationLab
m_world->GetDisplayListManager()->RemoveDisplayList(m_displayListId);
}
void OnChange()
{
// some relevant changes are done when needed and not each frame
// hence display list can be sent only on this event
// it will be replaced in the NavigationLab
SendVisualdebug()
}
void SendVisualdebug()
{
ScopedDisplayList displayList(world);
// Following line use the id to replace the previous ScopedDisplayList if any by this newly constructed one.
// On first call since m_displayListId == KyUInt32MAXVal,
// it will assign m_displayListId with the result of m_world->GetDisplayListManager()->GenerateDisplayListId();
m_displayListId = displayList->InitUserControlledLifespan("MyDisplayList", "MyGroupOfDisplayLists", m_displayListId);
// ... use displayList as usual
}
}

With KY_BUILD_SHIPPING defined, this class is still present but replaced by a fully inlined emptied version.

+ Examples:

Constructors

Construct a ScopedDisplayList, then, you must call one of the InitSingleFrameLifespan function in order to classify the DisplayList in the NavigationLab.

Lifespan of a ScopedDisplayList is determined by the Init function, the ScopedDisplayList will be either available one single frame so you have to send it over several frames in order to see it several frames, or you can control its lifetime by assigning it an id, that must be provided by the DisplayListManager.

ScopedDisplayList with same name and same group will have their display control together under one section and one label in the NavigationLab. however, lifespan remains individual.

 ScopedDisplayList (DisplayListManager *manager, DisplayListActivation activation=DisplayList_Enable)
 
 ScopedDisplayList (World *world, DisplayListActivation activation=DisplayList_Enable)
 

Init for ScopedDisplayList stored only in the frame it was sent

A name and a group identifier are mandatory.

They allow to sort display lists in the NavigationLab UI and turning their display on/off.

A group identifier is either a name or a worldElementID.

This ScopedDisplayList will be only available the frame it is sent

void InitSingleFrameLifespan (const char listName[64], const char groupName[64])
 
void InitSingleFrameLifespan (const char listName[64], KyUInt32 worldElementId)
 
void InitSingleFrameLifespan (const char listName[64], const char groupName[64], KyUInt32 worldElementId)
 

Init for ScopedDisplayList with User-Controlled Lifespan

As above, a name and a group identifier are mandatory.

Assigning a lifespan identifier allows to control the lifespan of the display list over several frames, sending back this id via DisplayListManager::RemoveDisplayLIst(displayListId) will stop displaying the list.

Not calling this function will display the list for only one frame.

If a ScopedDisplayList is sent with the same displayListId the previous one will be replaced. displayListId must be provided by DisplayListManager::GenerateDisplayListId(), or its value must be KyUInt32MAXVal so DisplayListManager::GenerateDisplayListId() will be called and the returned value must be assign to a maintained displayListId e.g. /code { m_displayListId = KyUInt32MAXVAL; // initialized somewhere, out of the fonction creating the displayList // ... // later in your code in a function that creates a displayList: // so first time you call this function m_displayListId is assigned and used // next calls to this function will simply use m_displayListId m_displayListId = scopedDisplayList.InitUserControlledLifespan("myList", "myGroup", m_displayListId); } /endcode Alternatively, /code { m_displayListId = m_world->GetDisplayListManager()->GenerateDisplayListId(); // initialized somewhere, out of the fonction creating the displayList // ... // later in your code in a function that creates a displayList: m_displayListId = scopedDisplayList.InitUserControlledLifespan("myList", "myGroup", m_displayListId); // the return value could be ignored since it is m_displayListId. } /endcode

KyUInt32 InitUserControlledLifespan (const char listName[64], const char groupName[64], KyUInt32 displayListId)
 
KyUInt32 InitUserControlledLifespan (const char listName[64], KyUInt32 worldElementId, KyUInt32 displayListId)
 
KyUInt32 InitUserControlledLifespan (const char listName[64], const char groupName[64], KyUInt32 worldElementId, KyUInt32 displayListId)
 
void InitUserControlledLifespan (const char listName[64], const char groupName[64])
 
void InitUserControlledLifespan_AssociateWithWorldElement (const char listName[64], const char groupName[64], KyUInt32 worldElementId)
 

Optional post-Init functions

void ShowInLabWhenSelected (bool showInLabWhenSelected)
 
void ShowInLabWhenNotSelected (bool showInLabWhenNotSelected)
 
void ShowInLab (bool showInLab)
 

Shapes

void PushTextVarg (const Vec3f &pos, const VisualColor &color, const char *textFmt,...)
 
void PushText (const Vec3f &pos, const VisualColor &color, const char *text, KyUInt32 textLength=0)
 
void PushLine (const Vec3f &P, const Vec3f &Q, const VisualColor &color, KyFloat32 pixelWidth=1.f)
 
void PushTriangle (const Vec3f &A, const Vec3f &B, const Vec3f &C, const VisualShapeColor &color)
 
void PushTriangle (const Triangle3f &triangle, const VisualShapeColor &color)
 
void PushVerticalCylinder (const Vec3f &P, KyFloat32 radius, KyFloat32 height, KyUInt32 subdivisions, const VisualShapeColor &color)
 
void PushSegment (const Vec3f &A, const Vec3f &B, KyFloat32 radius, const VisualShapeColor &color)
 
void PushQuad (const Vec3f &A, const Vec3f &B, KyFloat32 radius, const VisualShapeColor &color)
 
void PushQuad (const Vec3f &A, const Vec3f &B, const Vec3f &C, const Vec3f &D, const VisualShapeColor &color)
 
void PushPoint (const Vec3f &P, const VisualShapeColor &color)
 
void PushPoint (const Vec3f &P, KyFloat32 radius, const VisualShapeColor &color)
 
void PushPyramid (const Vec3f &P, const Vec3f &Q, KyFloat32 halfWidth, const VisualShapeColor &color)
 
void PushSquareTubeSegment (const Vec3f &P, const Vec3f &Q, KyFloat32 halfWidth, const VisualShapeColor &color)
 
void PushArrow (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color, KyFloat32 headWidthRatio=3.0f, KyFloat32 headLengthRatio=0.33f)
 
void PushBezierArrow (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color, KyFloat32 headWidthRatio=3.0f, KyUInt32 directionnality=0)
 
void PushChristmasTree (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color)
 
void PushSilex (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color)
 
void PushDoubleSilex (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color)
 
void PushCrossedRectangles (const Vec3f &P, const Vec3f &Q, KyFloat32 bodyHalfWidth, const VisualShapeColor &color)
 
void PushColumn (const Vec3f &P, KyFloat32 halfWidth, KyFloat32 height, const VisualShapeColor &color)
 
void PushOrientedBox (const Transform &transform, const Box3f &extents, const VisualShapeColor &color)
 
void PushOrientedBox2d (const OrientedBox2d &orientedBox2d, const VisualShapeColor &color)
 
void PushPoint_Tetrahedron (const Vec3f &P, KyFloat32 halfWidth, const VisualShapeColor &color)
 
void PushDisk (const Vec3f &P, KyFloat32 radius, KyUInt32 subdivisions, const VisualShapeColor &color)
 
void PushDiskSector (const Vec3f &P, KyFloat32 radius, const Vec3f &startPos, const Vec3f &endPos, const RotationDirection rotDir, KyUInt32 subdivisionCount, const VisualShapeColor &color)
 
void PushCorona (const Vec3f &P, KyFloat32 innerRadius, KyFloat32 outerRadius, KyUInt32 subdivisions, const VisualShapeColor &color)
 
void PushStadium (const Vec3f &P, const Vec3f &Q, KyFloat32 radius, KyUInt32 subdivisions, const VisualShapeColor &color)
 
void PushBox (const Box3f &box, const VisualShapeColor &color)
 
void PushCellBox (const Box2i &cellBox, const KyFloat32 altitudeMinMax[], const DatabaseGenMetrics &genMetrics, const VisualShapeColor &color)
 
void PushTriangleTubeSegment (const Vec3f &P, const Vec3f &Q, KyFloat32 halfWidth, const VisualShapeColor &color)
 
void PushWall (const Vec3f &P, const Vec3f &Q, KyFloat32 upHeight, KyFloat32 downHeight, KyFloat32 halfWidth, const VisualShapeColor &color)
 
void PushLadder (const Transform &transform, const Box3f &entrances, KyFloat32 ladderWidth, KyFloat32 rungsThickness, KyFloat32 rungsGapSize, const VisualShapeColor &shapeColor)
 
void PushParabola (const Kaim::Vec3f &P, const Kaim::Vec3f &Q, KyFloat32 heightBias, KyUInt32 subdivisions, const VisualShapeColor &color)
 
void PushFlag (const Vec3f &P, KyFloat32 height, KyFloat32 radius, const VisualShapeColor &color)
 

For internal use only

DisplayListManagerm_displayListManager
 
DisplayListData * m_displayListData
 
 ~ScopedDisplayList ()
 
void Flush ()
 
DisplayListManagerGetManager ()
 

Constructor & Destructor Documentation

Kaim::ScopedDisplayList::ScopedDisplayList ( World world,
DisplayListActivation  activation = DisplayList_Enable 
)

same as above, world->GetDisplayListManager() is used internally to provide the DisplayListManager

Member Function Documentation

void Kaim::ScopedDisplayList::InitSingleFrameLifespan ( const char  listName[64],
const char  groupName[64] 
)

group all displayLists with the same groupName under the same label

+ Examples:
void Kaim::ScopedDisplayList::InitSingleFrameLifespan ( const char  listName[64],
KyUInt32  worldElementId 
)

associate the displayList to the given world element and so the list can then be turned on/off under the section of the world element type

void Kaim::ScopedDisplayList::InitSingleFrameLifespan ( const char  listName[64],
const char  groupName[64],
KyUInt32  worldElementId 
)

associate the displayList to the given world element and so the list can then be turned on/off under the section of the world element type

KyUInt32 Kaim::ScopedDisplayList::InitUserControlledLifespan ( const char  listName[64],
const char  groupName[64],
KyUInt32  displayListId 
)

group all displayLists with the same groupName under the same label

+ Examples:
KyUInt32 Kaim::ScopedDisplayList::InitUserControlledLifespan ( const char  listName[64],
KyUInt32  worldElementId,
KyUInt32  displayListId 
)

associate the displayList to the given world element and so the list can then be turned on/off under the section of the world element type

KyUInt32 Kaim::ScopedDisplayList::InitUserControlledLifespan ( const char  listName[64],
const char  groupName[64],
KyUInt32  worldElementId,
KyUInt32  displayListId 
)

associate the displayList to the given world element and so the list can then be turned on/off under the section of the world element type

void Kaim::ScopedDisplayList::InitUserControlledLifespan ( const char  listName[64],
const char  groupName[64] 
)

group all displayLists with the same groupName under the same label

void Kaim::ScopedDisplayList::InitUserControlledLifespan_AssociateWithWorldElement ( const char  listName[64],
const char  groupName[64],
KyUInt32  worldElementId 
)

Associate the displayList to the given world element and so the list can then be turned on/off under the section of the world element type.

If the same name and worldElementId is used, this display list will overwrite the previous displayList To destroy this display list, call DisplayListManager::RemoveDisplayList(listName); If the element is destroyed, the display list will be automatically destroyed Returns the Id generated from the name

void Kaim::ScopedDisplayList::PushArrow ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color,
KyFloat32  headWidthRatio = 3.0f,
KyFloat32  headLengthRatio = 0.33f 
)

Pushes an arrow from P to Q.

Parameters
PStarting point of the arrow.
QEnding point of the arrow.
bodyHalfWidthHalf of the width of the body or trunk of the arrow.
colorColor of the arrow.
headWidthRatioThe ratio between the width of the head and the width of the body. In other words, the head or point of the arrow will be this many times wider than the body or trunk of the arrow.

default value:  3.0f.

Parameters
headLengthRatioThe ratio between the length of the head and the length of the body. In other words, the head or point of the arrow will be this many times longer than the body or trunk of the arrow.

default value:  0.33f.

+ Examples:
void Kaim::ScopedDisplayList::PushBezierArrow ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color,
KyFloat32  headWidthRatio = 3.0f,
KyUInt32  directionnality = 0 
)

Pushes a bezier arrow from P to Q.

Parameters
PStarting point of the arrow.
QEnding point of the arrow.
bodyHalfWidthHalf of the width of the body or trunk of the arrow.
colorColor of the arrow.
headWidthRatioThe ratio between the width of the head and the width of the body. In other words, the head or point of the arrow will be this many times wider than the body or trunk of the arrow.

default value:  3.0f

Parameters
directionnalityIf 0, has no arrow. If 1, has an arrow at the end. If 2, has an arrow at start and end.

default value:  0

void Kaim::ScopedDisplayList::PushBox ( const Box3f box,
const VisualShapeColor &  color 
)

Pushes an axis-aligned box.

+ Examples:
void Kaim::ScopedDisplayList::PushCellBox ( const Box2i cellBox,
const KyFloat32  altitudeMinMax[],
const DatabaseGenMetrics genMetrics,
const VisualShapeColor &  color 
)

Pushes a Box from a CellBox using -altitude and +altitude for z values for min and max.

void Kaim::ScopedDisplayList::PushChristmasTree ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color 
)

Pushes a Christmas tree: two orthogonal triangles with the same central axes.

P is the center of the base of both triangles, and Q is at the top of both triangles. Both triangles extend a distance of bodyHalfWidth from the central axes.

void Kaim::ScopedDisplayList::PushColumn ( const Vec3f P,
KyFloat32  halfWidth,
KyFloat32  height,
const VisualShapeColor &  color 
)

Pushes an axis-aligned box whose base is centered on P.

void Kaim::ScopedDisplayList::PushCorona ( const Vec3f P,
KyFloat32  innerRadius,
KyFloat32  outerRadius,
KyUInt32  subdivisions,
const VisualShapeColor &  color 
)

Pushes a 2D flat corona centered on P.

void Kaim::ScopedDisplayList::PushCrossedRectangles ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color 
)

Pushes two orthogonal rectangles with the same central axes.

P is the center of one end of both rectangles, and Q is at the center of the opposite end of both rectangles. Both rectangles extend a distance of bodyHalfWidth from the central axes.

void Kaim::ScopedDisplayList::PushDisk ( const Vec3f P,
KyFloat32  radius,
KyUInt32  subdivisions,
const VisualShapeColor &  color 
)

Pushes a 2D flat disk centered on P.

void Kaim::ScopedDisplayList::PushDiskSector ( const Vec3f P,
KyFloat32  radius,
const Vec3f startPos,
const Vec3f endPos,
const RotationDirection  rotDir,
KyUInt32  subdivisionCount,
const VisualShapeColor &  color 
)

Pushes a 2D flat disk sector centered on P, between start and end positions (on the circle).

void Kaim::ScopedDisplayList::PushDoubleSilex ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color 
)

Pushes a double silex from P to Q with the specified bodyHalfWidth.

Equivalent to a silex from P to the midpoint between P and Q, and a silex from Q to the midpoint between P and Q.

void Kaim::ScopedDisplayList::PushLine ( const Vec3f P,
const Vec3f Q,
const VisualColor color,
KyFloat32  pixelWidth = 1.f 
)
void Kaim::ScopedDisplayList::PushPoint ( const Vec3f P,
const VisualShapeColor &  color 
)
inline

Pushes an axis-aligned box centered on P. Or, a cross made of lines.

+ Examples:
void Kaim::ScopedDisplayList::PushPoint ( const Vec3f P,
KyFloat32  radius,
const VisualShapeColor &  color 
)

Pushes an axis-aligned box centered on P. Or, a cross made of lines.

void Kaim::ScopedDisplayList::PushPoint_Tetrahedron ( const Vec3f P,
KyFloat32  halfWidth,
const VisualShapeColor &  color 
)

Pushes an axis-aligned tetrahedron centered on P and pointing down.

void Kaim::ScopedDisplayList::PushPyramid ( const Vec3f P,
const Vec3f Q,
KyFloat32  halfWidth,
const VisualShapeColor &  color 
)

Push a pyramid composed of a base and four sides. P the is center of the base, Q is the peak.

void Kaim::ScopedDisplayList::PushQuad ( const Vec3f A,
const Vec3f B,
KyFloat32  radius,
const VisualShapeColor &  color 
)

Pushes a flat Quad.

void Kaim::ScopedDisplayList::PushQuad ( const Vec3f A,
const Vec3f B,
const Vec3f C,
const Vec3f D,
const VisualShapeColor &  color 
)

Pushes a flat Quad.

void Kaim::ScopedDisplayList::PushSegment ( const Vec3f A,
const Vec3f B,
KyFloat32  radius,
const VisualShapeColor &  color 
)

Pushes a segment. P and Q are the centers of the two opposite ends, and halfWidth is half the width of the segment.

void Kaim::ScopedDisplayList::PushSilex ( const Vec3f P,
const Vec3f Q,
KyFloat32  bodyHalfWidth,
const VisualShapeColor &  color 
)

Pushes a silex from P to Q with the specified bodyHalfWidth.

void Kaim::ScopedDisplayList::PushSquareTubeSegment ( const Vec3f P,
const Vec3f Q,
KyFloat32  halfWidth,
const VisualShapeColor &  color 
)

Pushes a hollow tube with a square cross-section.

P and Q are at the center of two opposite faces, and the width of the tube is equal to twicehalfWidth.

void Kaim::ScopedDisplayList::PushTextVarg ( const Vec3f pos,
const VisualColor color,
const char *  textFmt,
  ... 
)

Pushes a text.

+ Examples:
void Kaim::ScopedDisplayList::PushTriangle ( const Vec3f A,
const Vec3f B,
const Vec3f C,
const VisualShapeColor &  color 
)

Pushes a single triangle.

void Kaim::ScopedDisplayList::PushTriangle ( const Triangle3f triangle,
const VisualShapeColor &  color 
)

Pushes a single triangle.

void Kaim::ScopedDisplayList::PushTriangleTubeSegment ( const Vec3f P,
const Vec3f Q,
KyFloat32  halfWidth,
const VisualShapeColor &  color 
)

Pushes a hollow tube with a triangular cross-section.

P and Q are at the center of two opposite faces, and the width of the tube is equal to twicehalfWidth.

void Kaim::ScopedDisplayList::PushVerticalCylinder ( const Vec3f P,
KyFloat32  radius,
KyFloat32  height,
KyUInt32  subdivisions,
const VisualShapeColor &  color 
)

Pushes a cylinder whose base is centered on P.

+ Examples:
void Kaim::ScopedDisplayList::PushWall ( const Vec3f P,
const Vec3f Q,
KyFloat32  upHeight,
KyFloat32  downHeight,
KyFloat32  halfWidth,
const VisualShapeColor &  color 
)

Pushes a three-dimensional oriented box.

Parameters
PA point at one end of the box.
QA point at the opposite end of the box.
upHeightThe distance of the top of the box above P and Q.
downHeightThe distance of the bottom of the box below P and Q.
halfWidthThe distance of the sides of the box on either side of P and Q.
colorColor of the wall.
void Kaim::ScopedDisplayList::ShowInLab ( bool  showInLab)

Makes the NavigationLab hide the displayList whether it's selected or NOT selected. The NavigationLab UI allows to override this.

void Kaim::ScopedDisplayList::ShowInLabWhenNotSelected ( bool  showInLabWhenNotSelected)

Makes the NavigationLab display or hide the displayList when the corresponding Element (Bot, obstacle...) is NOT selected.

The NavigationLab UI allows to override this. showInLabWhenNotSelected is true by default.

void Kaim::ScopedDisplayList::ShowInLabWhenSelected ( bool  showInLabWhenSelected)

Makes the NavigationLab display or hide the displayList when the corresponding Element (Bot, obstacle...) is selected.

The NavigationLab UI allows to override this. showInLabWhenSelected is true by default.


The documentation for this class was generated from the following file: