OGRE  1.10.12
Object-Oriented Graphics Rendering Engine
Overlay Scripts

Overlay scripts offer you the ability to define overlays in a script which can be reused easily. Whilst you could set up all overlays for a scene in code using the methods of the SceneManager, Overlay and OverlayElement classes, in practice it’s a bit unwieldy. Instead you can store overlay definitions in text files which can then be loaded whenever required.

Loading scripts

Overlay scripts are loaded at initialisation time by the system: by default it looks in all common resource locations (see Root::addResourceLocation) for files with the ’.overlay’ extension and parses them. If you want to parse files with a different extension, use the OverlayManager::getSingleton().parseAllSources method with your own extension, or if you want to parse an individual file, use OverlayManager::getSingleton().parseScript.

Format

Several overlays may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces ({}), comments indicated by starting a line with ’//’ (note, no nested form comments allowed), and inheritance through the use of templates. The general format is shown below in a typical example:

// The name of the overlay comes first
overlay MyOverlays/ANewOverlay
{
zorder 200
container Panel(MyOverlayElements/TestPanel)
{
// Center it horizontally, put it at the top
left 0.25
top 0
width 0.5
height 0.1
material MyMaterials/APanelMaterial
// Another panel nested in this one
container Panel(MyOverlayElements/AnotherPanel)
{
left 0
top 0
width 0.1
height 0.1
material MyMaterials/NestedPanel
}
}
}

The above example defines a single overlay called ’MyOverlays/ANewOverlay’, with 2 panels in it, one nested under the other. It uses relative metrics (the default if no metrics_mode option is found).

Every overlay in the script must be given a name, which is the line before the first opening ’{’. This name must be globally unique. It can include path characters (as in the example) to logically divide up your overlays, and also to avoid duplicate names, but the engine does not treat the name a hierarchical, just as a string. Within the braces are the properties of the overlay, and any nested elements. The overlay itself only has a single property ’zorder’ which determines how ’high’ it is in the stack of overlays if more than one is displayed at the same time. Overlays with higher zorder values are displayed on top.

Adding elements to the overlay

Within an overlay, you can include any number of 2D or 3D elements. You do this by defining a nested block headed by:

’element’

if you want to define a 2D element which cannot have children of it’s own

’container’

if you want to define a 2D container object (which may itself have nested containers or elements)


The element and container blocks are pretty identical apart from their ability to store nested blocks.

’container’ / ’element’ blocks

These are delimited by curly braces. The format for the header preceding the first brace is:

[container | element] <type_name> ( <instance_name>) [: <template_name>]
{ ...

type_name

Must resolve to the name of a OverlayElement type which has been registered with the OverlayManager. Plugins register with the OverlayManager to advertise their ability to create elements, and at this time advertise the name of the type. OGRE comes preconfigured with types ’Panel’, ’BorderPanel’ and ’TextArea’.

instance_name

Must be a name unique among all other elements / containers by which to identify the element. Note that you can obtain a pointer to any named element by calling OverlayManager::getSingleton().getOverlayElement(name).

template_name

Optional template on which to base this item. See templates.

The properties which can be included within the braces depend on the custom type. However the following are always valid:

Templates

You can use templates to create numerous elements with the same properties. A template is an abstract element and it is not added to an overlay. It acts as a base class that elements can inherit and get its default properties. To create a template, the keyword ’template’ must be the first word in the element definition (before container or element). The template element is created in the topmost scope - it is NOT specified in an Overlay. It is recommended that you define templates in a separate overlay though this is not essential. Having templates defined in a separate file will allow different look & feels to be easily substituted.

Elements can inherit a template in a similar way to C++ inheritance - by using the : operator on the element definition. The : operator is placed after the closing bracket of the name (separated by a space). The name of the template to inherit is then placed after the : operator (also separated by a space).

A template can contain template children which are created when the template is subclassed and instantiated. Using the template keyword for the children of a template is optional but recommended for clarity, as the children of a template are always going to be templates themselves.

template container BorderPanel(MyTemplates/BasicBorderPanel)
{
left 0
top 0
width 1
height 1
// setup the texture UVs for a borderpanel
// do this in a template so it doesn't need to be redone everywhere
material Core/StatsBlockCenter
border_size 0.05 0.05 0.06665 0.06665
border_material Core/StatsBlockBorder
border_topleft_uv 0.0000 1.0000 0.1914 0.7969
border_top_uv 0.1914 1.0000 0.8086 0.7969
border_topright_uv 0.8086 1.0000 1.0000 0.7969
border_left_uv 0.0000 0.7969 0.1914 0.2148
border_right_uv 0.8086 0.7969 1.0000 0.2148
border_bottomleft_uv 0.0000 0.2148 0.1914 0.0000
border_bottom_uv 0.1914 0.2148 0.8086 0.0000
border_bottomright_uv 0.8086 0.2148 1.0000 0.0000
}
template container Button(MyTemplates/BasicButton) : MyTemplates/BasicBorderPanel
{
left 0.82
top 0.45
width 0.16
height 0.13
material Core/StatsBlockCenter
border_up_material Core/StatsBlockBorder/Up
border_down_material Core/StatsBlockBorder/Down
}
template element TextArea(MyTemplates/BasicText)
{
font_name Ogre
char_height 0.08
colour_top 1 1 0
colour_bottom 1 0.2 0.2
left 0.03
top 0.02
width 0.12
height 0.09
}
overlay MyOverlays/AnotherOverlay
{
zorder 490
container BorderPanel(MyElements/BackPanel) : MyTemplates/BasicBorderPanel
{
left 0
top 0
width 1
height 1
container Button(MyElements/HostButton) : MyTemplates/BasicButton
{
left 0.82
top 0.45
caption MyTemplates/BasicText HOST
}
container Button(MyElements/JoinButton) : MyTemplates/BasicButton
{
left 0.82
top 0.60
caption MyTemplates/BasicText JOIN
}
}
}

The above example uses templates to define a button. Note that the button template inherits from the borderPanel template. This reduces the number of attributes needed to instantiate a button.

Also note that the instantiate of a Button needs a template name for the caption attribute. So templates can also be used by elements that need dynamic creation of children elements (the button creates a TextAreaElement in this case for its caption).

See OverlayElement Attributes, Standard OverlayElements

OverlayElement Attributes

These attributes are valid within the braces of a ’container’ or ’element’ block in an overlay script. They must each be on their own line. Ordering is unimportant.

metrics_mode

Sets the units which will be used to size and position this element.

Format: metrics_mode <pixels|relative>
Example: metrics_mode pixels

This can be used to change the way that all measurement attributes in the rest of this element are interpreted. In relative mode, they are interpreted as being a parametric value from 0 to 1, as a proportion of the width / height of the screen. In pixels mode, they are simply pixel offsets.

Default: metrics_mode relative

horz_align

Sets the horizontal alignment of this element, in terms of where the horizontal origin is.

Format: horz_align <left|center|right>
Example: horz_align center

This can be used to change where the origin is deemed to be for the purposes of any horizontal positioning attributes of this element. By default the origin is deemed to be the left edge of the screen, but if you change this you can center or right-align your elements. Note that setting the alignment to center or right does not automatically force your elements to appear in the center or the right edge, you just have to treat that point as the origin and adjust your coordinates appropriately. This is more flexible because you can choose to position your element anywhere relative to that origin. For example, if your element was 10 pixels wide, you would use a ’left’ property of -10 to align it exactly to the right edge, or -20 to leave a gap but still make it stick to the right edge.

Note that you can use this property in both relative and pixel modes, but it is most useful in pixel mode.

Default: horz_align left

vert_align

Sets the vertical alignment of this element, in terms of where the vertical origin is.

Format: vert_align <top|center|bottom>
Example: vert_align center

This can be used to change where the origin is deemed to be for the purposes of any vertical positioning attributes of this element. By default the origin is deemed to be the top edge of the screen, but if you change this you can center or bottom-align your elements. Note that setting the alignment to center or bottom does not automatically force your elements to appear in the center or the bottom edge, you just have to treat that point as the origin and adjust your coordinates appropriately. This is more flexible because you can choose to position your element anywhere relative to that origin. For example, if your element was 50 pixels high, you would use a ’top’ property of -50 to align it exactly to the bottom edge, or -70 to leave a gap but still make it stick to the bottom edge.

Note that you can use this property in both relative and pixel modes, but it is most useful in pixel mode.

Default: vert_align top

left

Sets the horizontal position of the element relative to it’s parent.

Format: left <value>
Example: left 0.5

Positions are relative to the parent (the top-left of the screen if the parent is an overlay, the top-left of the parent otherwise) and are expressed in terms of a proportion of screen size. Therefore 0.5 is half-way across the screen.

Default: left 0

top

Sets the vertical position of the element relative to it’s parent.

Format: top <value>
Example: top 0.5

Positions are relative to the parent (the top-left of the screen if the parent is an overlay, the top-left of the parent otherwise) and are expressed in terms of a proportion of screen size. Therefore 0.5 is half-way down the screen.

Default: top 0

width

Sets the width of the element as a proportion of the size of the screen.

Format: width <value>
Example: width 0.25

Sizes are relative to the size of the screen, so 0.25 is a quarter of the screen. Sizes are not relative to the parent; this is common in windowing systems where the top and left are relative but the size is absolute.

Default: width 1

height

Sets the height of the element as a proportion of the size of the screen.

Format: height <value>
Example: height 0.25

Sizes are relative to the size of the screen, so 0.25 is a quarter of the screen. Sizes are not relative to the parent; this is common in windowing systems where the top and left are relative but the size is absolute.

Default: height 1

material

Sets the name of the material to use for this element.

Format: material <name>
Example: material Examples/TestMaterial

This sets the base material which this element will use. Each type of element may interpret this differently; for example the OGRE element ’Panel’ treats this as the background of the panel, whilst ’BorderPanel’ interprets this as the material for the center area only. Materials should be defined in .material scripts. Note that using a material in an overlay element automatically disables lighting and depth checking on this material. Therefore you should not use the same material as is used for real 3D objects for an overlay.

Default: none

caption

Sets a text caption for the element.

Format: caption <string>
Example: caption This is a caption

Not all elements support captions, so each element is free to disregard this if it wants. However, a general text caption is so common to many elements that it is included in the generic interface to make it simpler to use. This is a common feature in GUI systems.

Default: blank

rotation

Sets the rotation of the element.

Format: rotation <angle_in_degrees> <axis_x> <axis_y> <axis_z> Example: rotation 30 0 0 1

Default: none

Standard OverlayElements

Although OGRE’s OverlayElement and OverlayContainer classes are designed to be extended by applications developers, there are a few elements which come as standard with Ogre. These include:

This section describes how you define their custom attributes in an .overlay script, but you can also change these custom properties in code if you wish. You do this by calling setParameter(param, value). You may wish to use the StringConverter class to convert your types to and from strings.

Panel (container)

This is the most bog-standard container you can use. It is a rectangular area which can contain other elements (or containers) and may or may not have a background, which can be tiled however you like. The background material is determined by the material attribute, but is only displayed if transparency is off.

Parameters
transparent<true | false> If set to ’true’ the panel is transparent and is not rendered itself, it is just used as a grouping level for it’s children.
tiling<layer> <x_tile> <y_tile> Sets the number of times the texture(s) of the material are tiled across the panel in the x and y direction. <layer> is the texture layer, from 0 to the number of texture layers in the material minus one. By setting tiling per layer you can create some nice multitextured backdrops for your panels, this works especially well when you animate one of the layers.
uv_coords<topleft_u> <topleft_v> <bottomright_u> <bottomright_v> Sets the texture coordinates to use for this panel.

BorderPanel (container)

This is a slightly more advanced version of Panel, where instead of just a single flat panel, the panel has a separate border which resizes with the panel. It does this by taking an approach very similar to the use of HTML tables for bordered content: the panel is rendered as 9 square areas, with the center area being rendered with the main material (as with Panel) and the outer 8 areas (the 4 corners and the 4 edges) rendered with a separate border material. The advantage of rendering the corners separately from the edges is that the edge textures can be designed so that they can be stretched without distorting them, meaning the single texture can serve any size panel.

Parameters
border_size<left> <right> <top> <bottom> The size of the border at each edge, as a proportion of the size of the screen. This lets you have different size borders at each edge if you like, or you can use the same value 4 times to create a constant size border.
border_material<name> The name of the material to use for the border. This is normally a different material to the one used for the center area, because the center area is often tiled which means you can’t put border areas in there. You must put all the images you need for all the corners and the sides into a single texture.
border_topleft_uv<u1> <v1> <u2> <v2> [also border_topright_uv, border_bottomleft_uv, border_bottomright_uv]; The texture coordinates to be used for the corner areas of the border. 4 coordinates are required, 2 for the top-left corner of the square, 2 for the bottom-right of the square.
border_left_uv<u1> <v1> <u2> <v2> [also border_right_uv, border_top_uv, border_bottom_uv]; The texture coordinates to be used for the edge areas of the border. 4 coordinates are required, 2 for the top-left corner, 2 for the bottom-right. Note that you should design the texture so that the left & right edges can be stretched / squashed vertically and the top and bottom edges can be stretched / squashed horizontally without detrimental effects.

TextArea (element)

This is a generic element that you can use to render text. It uses fonts which can be defined in code using the FontManager and Font classes, or which have been predefined in .fontdef files. See the font definitions section for more information.

Parameters
font_name<name> The name of the font to use. This font must be defined in a .fontdef file to ensure it is available at scripting time.
char_height<height> The height of the letters as a proportion of the screen height. Character widths may vary because OGRE supports proportional fonts, but will be based on this constant height.
colour<red> <green> <blue> A solid colour to render the text in. Often fonts are defined in monochrome, so this allows you to colour them in nicely and use the same texture for multiple different coloured text areas. The colour elements should all be expressed as values between 0 and 1. If you use predrawn fonts which are already full colour then you don’t need this.
colour_bottom<red> <green> <blue>
colour_top<red> <green> <blue> As an alternative to a solid colour, you can colour the text differently at the top and bottom to create a gradient colour effect which can be very effective.
alignment<left | center | right> Sets the horizontal alignment of the text. This is different from the horz_align parameter.
space_width<width> Sets the width of a space in relation to the screen.