Conventions

Introduction

Background

Everyone loves conventions! What could be more exciting than splitting hairs about the smallest difference in meaning semantics between two words?

In this document we try to outline our motivations behind conventions in general, some guidelines to use when creating them and, of course, an always incomplete list of the conventions we use inside the engine today.

Motivations and goals

What is a convention, anyway? A convention is a shared way of doing things. Other people may do this same thing another way, or perhaps may do it many different ways, but we do these things this way.

Why have conventions in a software projects though? The idea is to follow the principle of least surprise. If I access a variable called position, I wouldn't, for example, expect to get that object's velocity.

That makes sense - the variable should give you something you expect. But what if position returns an Isometry3 in one case and a Vector3 in another? I would be very surprised!

Therein lies the real magic of conventions - they enforce consistency. As long as names are used consistently throughout a codebase, the actual name itself doesn't matter.

Conventions

Spaces

A space refers to a specific frame of reference for a coordinate system. When we say that an object has a translation of 10 on the x axis, it's 10 meters away from some specific origin point. We use a couple different spaces in Hotham:

• global refers to the space sometimes called "world space" in other engines. It's a space shared by all objects with some arbitrary origin.
• globally orientated stage (GOS) refers to a space whose origin is the location of the player's headset, with respect to the centre of their guardian (or stage, in OpenXR parlance). Importantly, only the translation of the player's headset is used - rotations are ignored. That sounds a bit complicated, but what it means in practice is that objects that are located close to the player are rendered with maximum precision, and precision errors are usually so far away from the player that they're not visible.
• local refers to some space that's only used by a single object. This is usually defined for models, who might have their origin to some logical point, such as the mid-point of the object, or the very bottom of the object (for example, between a human's feet, at the point where they touch the ground).

Positions, translations, rotations, orientations scales and transforms

There are many ways to describe where an object is located and what direction it's facing. We mostly stick to the glTF spec and use the following terms:

• translation to refer to an object's position, or location. Unless otherwise specified, this is in global space.
• rotation to refer to an object's orientation, or what direction it is facing.
• scale to refer to scaling or shearing of an object.
• transform to refer to a 4 dimensional matrix that represents the object's translation, rotation and scale in homogenous coordinates for use in rendering.