T1: Introduction to HIRO GUI

Overview

The use of the library is straightforward as shown in an example below. After you set default directories (lines 5-6), you can initialize the library (line 8). The main update cycle runs until the user closes the window (lines 10-13). Before the application ends, the library is terminated and deallocated (line 15).

#include <HIRO/HIRO.h>

int main()
{
  hiro::SetAssetDirectory("./hiro_libs/assets/");
  hiro::SetIntermediateDirectory("./temp/");

  hiro::Initialize();

  while (hiro::IsOpen())
  {
    hiro::Update();
  }

  hiro::Terminate();
  return 0;
}

The library depends on an asset directory, that must be located somewhere on the disk and set by the function SetAssetDirectory. If the directory is invalid or does not exist, the HIRO window cannot be initialized properly. HIRO also generates multiple files that help to restore the previous session when the program is started for another time. The path to the directory is set via SetIntermediateDirectory function.

Running the example code creates a blank window.

HIRO window has at least one viewarea, that consists of a viewport (A) where the data is visualized and a sidebar (B) providing rendering options and other controls. The sidebar has a resource inspector panel, that lists everything that can be visualized in the viewport. Currently, it does not show anything, because nothing has been added to HIRO yet. Let’s add a sample object.

Hint

If you run into any issues during using HIRO, try deleting the intermediate directory (or specific files in it) and run the program again.

Adding Data Resources

As is, HIRO does not know what and how it can visualize. For this, a data module must be created in the code where the data and rendering parameters are defined. Luckily for us, the library offers several data modules by default. Each data module has its resource, which is an object created by the user program and registered in the HIRO engine. In this example, we use a geometry module that has a GeometryResource object definition available (line 2), create an instance of it (lines 11-14) and add it to HIRO (line 15).

#include <HIRO/HIRO.h>
#include <HIRO/modules/GeometryResource.h>

int main()
{
  hiro::SetAssetDirectory("./hiro_libs/assets/");
  hiro::SetIntermediateDirectory("./temp/");

  hiro::Initialize();

  auto resource = std::make_shared<hiro::modules::GeometryResource>(
    "My first resource",
    hiro::draw::GeometryName::sphere_s2
  );
  hiro::AddResource(resource);

  while (hiro::IsOpen())
  {
    hiro::Update();
  }

  hiro::Terminate();
  return 0;
}

GeometryResource class has two construction parameters. The first one is the name. This parameter is required for almost every resource you encounter in the future, it defines how the specific resource object will be referred to later. The second parameter defines what type of geometry you want to create and visualize. This parameter is unique for GeometryResource object. All HIRO data resources are handled as shared pointers. You may hold the pointer in your program and manipulate the resource later, or you can release it and let only HIRO work with it.

Window now contains a single GeometryResource

When the program is run, a single resource is available in the resource inspector (its name is the same as we defined in code). After the resource is selected in the inspector, we can see the sphere object appear in the viewport.

A new panel was added to the sidebar in the same moment. This panel defines visualization options for the currently selected resource, in this case, GeometryResource. Try around all available options and remember, that anything you change, you change for this specific data module only - no general rendering parameters were modified!

Options

There are 3 groups of options available. The global options are opened by clicking on the cog in the sidebar. They contain settings to control and improve the overall user experience. The other two option panels view options and camera options are open when right-clicking on the viewport. These options influence only the viewport in which they were opened.

Global Options

White background

Render on white background. Useful for doing screenshots to printable documents papers.

Mouse sensitivity

The sensitivity of the mouse when applied to the movement of the camera.

Optimized rendering

Render only when something changes and needs to be redrawn.

If it is disabled, the engine updates the screen continuously. Enabling the feature will not let you correctly measure current fps. Disabling this option can cause the GPU to run in high utilization state.

Enable Shortcuts

Defines whether the system uses default keyboard shortcuts. If you do not wish to have default shortcuts enabled, turn off this option.

This can be useful when you wish to override the default key bindings, or some of the shortcuts negatively influence your experience.

MSAA

Set up the level of multi-sampled anti-aliasing. The higher the level, the visualization looks smoother, but can negatively impact performance. If you run into any performance issues, disable MSAA.

Select layout

Choose from several application layouts with more than one viewarea.

Reload shaders

Reload shader files to update for changes.

View and Camera Options

Draw global axes

Toggle to show world coordinate axes.

Grid

Selection to enable/disable ground grid visualization and define the orientation of the ground.

Grid cell units

Defines the size of a single ground grid square.

Mode

Allows setting rotational constraints for camera movement.

Near/far clipping planes

Minimum and maximum range from the camera, in which elements in the scene are rendered.

Reset camera view

Resets current camera pose into the default state.

Use when you get lost in the viewport.

Visual Debugger

There may be a case, when you wish to quickly visualize simple primitives, without having to create resource objects and selecting them in the window. For this purpose, HIRO offers a visual debugger directly built in API.

Visual debugger (or only debugger in the context of HIRO) is working at all times, in all viewareas. You can set commands to it via API directly by calling function hiro::GetDebugger() that returns a handle to debugger. The following code will produce the exact result shown in the picture above.

...
while (hiro::IsOpen())
{
  hiro::Debug().LogMessage("HIRO Debugger showcase!");

  const geom::Aabb3 box{ glm::vec3(-0.5f), glm::vec3(0.5f) };
  hiro::Debug().DrawBox(box);

  const geom::Sphere sphere{ glm::vec3(0.0f), 0.3f };
  hiro::Debug().DrawSphere(sphere, cogs::color::YELLOW);

  std::vector<geom::LineSegment3> lines{ geom::LineSegment3(0, -1, 0, 0, 1, 0) };
  hiro::Debug().DrawLines(lines);

  hiro::Update();
}
...

Note

By default, debugger draw calls will render for a single update cycle only. You can specify longer duration as an additional parameter to the draw functions.

Note

Current version of debugger allows drawing and logging only one unique item at a time. Multi-item rendering is planned for future updates.

Keyboard Shortcuts

Tab

Opens layout selection screen.

S

Toggles sidebar visibility for the viewarea under mouse cursor.

F11 or ALT+Enter

Enters/leaves window fullscreen mode.

Esc

Closes the HIRO window.

R

Reloads shader programs.