[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.1 Billboard

This is a property class to handle 2d on-screen billboards.

Property Class Details

General Information

You can use pcbillboard to handle an on-screen billboard and receive events when it is selected, unselected, clicked on, or when mouse moves over or out of it. Also it can draw a text or a mesh on itself, and allows restacking and moving of the billboard by the user.

It is useful as a base for creating a variety of simple interface controls, like buttons or hud elements.

This property class is controlled basically using properties through which you can define size, text, colours, and what events the billboard responds to.

It is common to use many pcbillboard property classes in one entity to create a complete interface, although not strictly necessary.

PcBillboards and Billboards

To avoid confusion, note the difference among PcBillboard, which is the property class this section talks about, and Billboards which are the actual objects PcBillboard controls (each PcBillboard controls one Billboard).

Billboard Space

Billboard coordinates (width, height, x and y) are specified in a special coordinate system called billboard space. This coordinate system system basically works on a virtual screen with size 307200 x 307200.

Billboard Message Callbacks

There is a variety of messages this property class can send which can be turned on or off by using the pcbillboard properties. Note by default all events are disabled.

Clicks can be controlled by the clickable property, and will send pcbillboard_select, pcbillboard_unselect or pcbillboard_doubleclick depending on the actual event.

MouseOver events can be controlled by the sendmove property, and will make the property class send pcbillboard_move and pcbillboard_moveaway events.

All pcbillboard messages get x, y and button arguments.

Controlling moving and restacking of billboards.

Billboards can be allowed to be moved around by the user by using the movable property.

They can also be allowed to be restacked on selection by using the restack property. If this is activated the billboard will be put on top of other overlapping billboards when selected.

Further control of billboards.

Check the iPcBillboard and iBillboard api to learn about all properties you can control, like text, text colour, billboard visibility, uv coordinates of underlying image. It is possible to draw a mesh on the billboard by using the DrawMesh action.

You should also be aware of the iBillboardManager cel component by which you can handle billboards (which are used by the pcbillboard property class), although you won't need it unless you are doing everything purely from code, or for advanced usage.

Defining a billboard for an entity in map xml.

To define an entity that uses this property class we add a <propclass> stance to the entity or entity template <addon> section.

<addon entityname="config_button" plugin="cel.addons.celentity">
  <propclass name="pc2d.billboard">
    <property name="clickable" bool="true"/>
    <property name="text" string="Quit"/>
    <property name="text_fg_color" vector="0.5,0,0"/>
    <property name="text_font_size" float="20.0"/>
    <property name="text_offset" vector2="10000,10000"/>
    <property name="x" long="61440"/>
    <property name="y" long="215039"/>
    <property name="text_font" string="/fonts/ttf/Vera.ttf"/>
    <property name="materialname" string="billboard_config_buttonbutton.png.001"/>
  <behaviour layer="blpython" name="config_button"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html 1.76.