Displays

Usage

Displays can be used to draw various vehicle instruments in the real time via ot::canvas interface.

How it works

First of all, you need to have some mesh with the display material in your model. Meshes with the display materials are considered to be the display meshes and you can query the display meshes names with get_displays_names method of the vehicle. On these meshes you can create displays by calling add_display method of the vehicle during the chassis initialization. It returns the id of the display, which is used to get the display ot::canvas interface you draw into. It is done via get_display_canvas method of vehicle. The returned ot::canvas interface can be empty when the display is not visible so don't forget to check it. You should call your display drawing routines in the render_displays event of the vehicle.

Display materials

You can define a material as the display material with adding prefix 'DISPLAY_' to the material name in you 3d modelling software or by changing the 'is_display' property of the material in the outerra material file.

Display meshes

As mentioned above, all the meshes with display materials are automatically considered as the display meshes. This meshes should be rectangular with UVs (0,0) coordinate in the left bottom corner and (1,1) in the right top corner.

Display dimensions and resolution

For now you must pass the display dimension in the pixels to add_display method of the vehicle, although we can automate this process by the detection of the mesh dimensions and calculation of the display dimensions via DPI resolution. However in the latter case, the display mesh must meet some conditions which will be specified when there will be demand for this solution. When you want to calculate the display dimensions in some selected DPI resolution you can use this formula:

display_width = mesh_width * DPI * 39.3700787
display_height = mesh_height * DPI * 39.3700787

The mesh_width and mesh_height are in meters and the result is in pixels.

Canvas coordinate system

If the UVs of the display mesh are specified correctly(as mentioned above), the display canvas has origin in the left bottom corner with the x axis pointing to the right and the y axis pointing up. The maximum coordinates are the dimensions of the display(width and height passed to the add_display method).

Basic workflow

The initialization of the displays must be done in the init_chasis event of the vehicle. Here you can get the array of the display meshes names with get_displays_names method of the vehicle and subsequently call the add_display method with chosen dimensions which will return the display id. For example:

var dpi2dpm = 39.3700787;
var DPI = 60;
var display_mesh_width = 0.245540;
var display_mesh_height = 0.15;
	
_display_width = Math.ceil(display_mesh_width * DPI * dpi2dpm);
_display_height = Math.ceil(display_mesh_height * DPI * dpi2dpm);

var displays_names = this.get_displays_names();
_display_id = this.add_display(_display_width, _display_height, displays_names[0]);

Now we have the display id and we can use it in render_displays event of the vehicle to get ot::canvas interface and draw to it. For example:

var t = 0;
function render_displays(dt)
{
    var green = { r: 0, g: 255, b: 0, a: 255 };
    var center_x = _display_width * 0.5;
    var center_y = _display_height * 0.5;
    var rect_wh = 50;
	
    var c = this.get_display_canvas(_display_id);
    if(c)
    {
        c.clear();
	c.translate(center_x,center_y);
	c.rotate(t);
        c.fill_rect(-rect_wh * 0.5, -rect_wh * 0.5, rect_wh, rect_wh, green);
		t += dt;
    }
}

This example code will render the green rectangle in the middle of the display which is rotating around its center. Note that we are calling canvas clear method each frame to clear the draw commands from the last frame. The more advanced example can be found in the script of outerra/buggy package where the digital speedometer is implemented.