Object - Atlas Engine

Overview

Atlas Engine provides three main object types for building 3D scenes:

CoreObject: Single mesh objects with vertices, materials, and textures
Model: Multi-mesh 3D models loaded from files
CompoundObject: Custom objects composed of multiple child objects

CoreObject

Represents a 3D object in the scene, including its geometry, material, and every interaction with the scene. It inherits from GameObject and can have Component classes attached for extended functionality.

Constructor

CoreObject();

Constructs a new CoreObject.

Properties

vertices

std::vector<CoreVertex>

The vertices of the object.

indices

std::vector<Index>

The indices of the object. These indicate how the vertices are connected to form faces.

shaderProgram

ShaderProgram

The shader program used to render the object.

textures

std::vector<Texture>

The textures applied to the object.

material

Material

The material properties of the object (albedo, metallic, roughness, ao).

instances

std::vector<Instance>

Vector of instances for instanced rendering. Multiple copies of the object can be rendered with different transforms efficiently.

position

Position3d

default:"{0.0, 0.0, 0.0}"

The position of the object in 3D space.

rotation

Rotation3d

default:"{0.0, 0.0, 0.0}"

The rotation of the object in 3D space.

scale

Scale3d

default:"{1.0, 1.0, 1.0}"

The scale of the object in 3D space.

castsShadows

bool

default:"true"

Variable that determines if the object casts shadows.

useDeferredRendering

bool

default:"true"

Whether the object should use deferred rendering. When false, the object is rendered in the forward rendering pass.

light

std::shared_ptr<Light>

The light attached to this object if it’s emissive. Used for emissive objects created with makeEmissive().

Geometry Methods

attachVertices

void attachVertices(const std::vector<CoreVertex> &newVertices);

Function to attach vertices and update the object’s vertex buffer.

newVertices

const std::vector<CoreVertex>&

The vertices to attach.

attachIndices

void attachIndices(const std::vector<Index> &newIndices);

Function to attach indices and update the object’s index buffer.

newIndices

const std::vector<Index>&

The indices to attach.

updateVertices

void updateVertices();

Function that updates the object’s vertex buffer.

Shader and Texture Methods

attachProgram

void attachProgram(const ShaderProgram &program);

Binds an already compiled shader program for this object.

program

const ShaderProgram&

The shader program to attach.

createAndAttachProgram

void createAndAttachProgram(VertexShader &vertexShader, FragmentShader &fragmentShader);

Builds a shader program from the supplied vertex and fragment sources, then binds it.

vertexShader

VertexShader&

The vertex shader.

fragmentShader

FragmentShader&

The fragment shader.

attachTexture

void attachTexture(const Texture &texture);

Adds a texture to the object and makes it available during rendering.

texture

const Texture&

The texture to attach.

Transform Methods

setPosition

void setPosition(const Position3d &newPosition);

Places the object at an absolute position in world space.

newPosition

const Position3d&

The new position.

move

void move(const Position3d &deltaPosition);

Moves the object relative to its current position.

deltaPosition

const Position3d&

The amount to move by.

setRotation

void setRotation(const Rotation3d &newRotation);

Assigns an absolute rotation to the object.

newRotation

const Rotation3d&

The new rotation in degrees.

setRotationQuat

void setRotationQuat(const glm::quat &quat);

Sets rotation using a quaternion.

quat

const glm::quat&

The quaternion rotation.

rotate

void rotate(const Rotation3d &deltaRotation);

Applies an incremental rotation around the object’s axes.

deltaRotation

const Rotation3d&

The rotation amount in degrees.

lookAt

void lookAt(const Position3d &target, const Normal3d &up = {0.0, 1.0, 0.0});

Rotates the object so its forward vector points towards a target.

target

const Position3d&

The point to look at.

const Normal3d&

default:"{0.0, 1.0, 0.0}"

The up vector.

setScale

void setScale(const Scale3d &newScale);

Uniformly scales the object along each axis.

newScale

const Scale3d&

The new scale.

Material and Rendering Methods

setColor

void setColor(const Color &color);

Sets a solid color override that multiplies with textures.

color

const Color&

The color to set.

makeEmissive

void makeEmissive(Scene *scene, Color emissionColor, float intensity);

Makes the object emissive by attaching a light to it.

scene

Scene*

The scene to add the light to.

emissionColor

Color

The color of the emitted light.

intensity

float

The intensity of the emitted light.

disableDeferredRendering

void disableDeferredRendering();

Switches the object to forward rendering by binding default shaders.

renderColorWithTexture

void renderColorWithTexture();

Function to render the object with color and texture.

renderOnlyColor

void renderOnlyColor();

Function to render the object with only its color.

renderOnlyTexture

void renderOnlyTexture();

Function to render the object with only its texture.

Visibility Methods

show

void show();

Makes the object visible.

hide

void hide();

Makes the object invisible.

Instancing Methods

createInstance

Instance& createInstance();

Creates and returns a new instance for instanced rendering.

return

Instance&

Reference to the newly created instance.

Utility Methods

clone

CoreObject clone() const;

Function that creates a copy of the object.

return

CoreObject

The cloned object.

initialize

void initialize();

Performs deferred setup of buffers, shaders, and state.

updateModelMatrix

void updateModelMatrix();

Function that updates the model matrix based on the object’s position, rotation, and scale.

Component Methods

addComponent

template <typename T>
void addComponent(T &&existing);

template <typename T>
void addComponent(const std::shared_ptr<T> &component);

Function that adds a component to the object. The component will have this CoreObject as its parent.

existing

T&&

The existing component to add.

The component must be long-lived. Declaring it as a class property is recommended.

Material Structure

Structure representing the material properties of an object. Based on PBR (Physically Based Rendering) principles.

albedo

Color

default:"{1.0, 1.0, 1.0, 1.0}"

Base color contribution of the surface.

metallic

float

default:"0.0f"

Metallic factor controlling how conductive the material behaves. Range: 0.0 (dielectric) to 1.0 (metal).

roughness

float

default:"0.5f"

Roughness factor influencing the spread of specular highlights. Range: 0.0 (smooth) to 1.0 (rough).

float

default:"1.0f"

Ambient occlusion term used to darken creases and cavities. Range: 0.0 (fully occluded) to 1.0 (no occlusion).

CoreVertex Structure

Structure representing a single vertex in 3D space.

position

Position3d

The position of the vertex in 3D space.

color

Color

default:"{1.0, 1.0, 1.0, 1.0}"

The color of the vertex.

textureCoordinate

TextureCoordinate

default:"{0.0, 0.0}"

The texture coordinates of the vertex (UV coordinates).

normal

Normal3d

default:"{0.0, 0.0, 0.0}"

The normal vector of the vertex, used for lighting calculations.

tangent

Normal3d

default:"{0.0, 0.0, 0.0}"

The tangent vector of the vertex, used for normal mapping and parallax calculations.

bitangent

Normal3d

default:"{0.0, 0.0, 0.0}"

The bitangent vector of the vertex, used for normal mapping and parallax calculations.

Instance Structure

Structure representing a single instance of an object for instanced rendering.

position

Position3d

default:"{0.0, 0.0, 0.0}"

The position of this instance in 3D space.

rotation

Rotation3d

default:"{0.0, 0.0, 0.0}"

The rotation of this instance in 3D space.

scale

Scale3d

default:"{1.0, 1.0, 1.0}"

The scale of this instance in 3D space.

Methods

void updateModelMatrix();
void move(const Position3d &deltaPosition);
void setPosition(const Position3d &newPosition);
void setRotation(const Rotation3d &newRotation);
void rotate(const Rotation3d &deltaRotation);
void setScale(const Scale3d &newScale);
void scaleBy(const Scale3d &deltaScale);
glm::mat4 getModelMatrix() const;

Model Class

Class that represents a 3D model composed of multiple CoreObjects. It can be loaded from a resource file and manages its constituent objects.

Methods

fromResource

void fromResource(const Resource &resource);

Loads the model from a resource.

resource

const Resource&

The resource to load the model from.

getObjects

std::vector<std::shared_ptr<CoreObject>> getObjects();

Gets the objects that make up the model.

return

std::vector<std::shared_ptr<CoreObject>>

The objects.

Transform Methods

The Model class supports the same transform methods as CoreObject:

move(const Position3d &deltaPosition)
setPosition(const Position3d &newPosition)
setRotation(const Rotation3d &newRotation)
setScale(const Scale3d &newScale)
attachTexture(const Texture &texture)

These methods apply the transformation to all constituent CoreObjects.

Properties

material

Material

The material properties shared by all objects in the model.

useDeferredRendering

bool

default:"true"

Whether the model should use deferred rendering.

CompoundObject Class

A CompoundObject is a GameObject that can be extended by the user to generate objects that encapsulate multiple CoreObjects. This is useful for creating complex objects that are made up of multiple simpler objects.

Creating a CompoundObject

class Car : public CompoundObject {
public:
    void init() override {
        // Create and add car body
        CoreObject *body = new CoreObject();
        // Set up body properties...
        addObject(body);
        
        // Add wheels, etc.
    }
    
    void updateObjects(Window &window) override {
        // Update car-specific logic, e.g., movement
    }
};

Methods

init

virtual void init();

Initializes the compound object. Override this to create and configure child objects.

initialize

virtual void initialize() override;

Bootstraps the compound object, initializing child objects and dispatching component hooks.

updateObjects

virtual void updateObjects(Window &window);

Updates the objects within the compound object.

window

Window&

The window where the objects are being rendered.

addObject

void addObject(GameObject *obj);

Adds a child object to the compound object.

obj

GameObject*

The object to add. Must be long-lived.

Transform Methods

The CompoundObject class supports all standard transform methods:

setPosition(const Position3d &newPosition)
move(const Position3d &deltaPosition)
setRotation(const Rotation3d &newRotation)
rotate(const Rotation3d &deltaRotation)
lookAt(const Position3d &target, const Normal3d &up)
setScale(const Scale3d &newScale)
show() and hide()

These methods apply the transformation to all child objects.

Properties

objects

std::vector<GameObject*>

The objects that make up the compound object.

Helper Functions

Primitive Creation

createBox

CoreObject createBox(Size3d size, Color color = {1.0, 1.0, 1.0, 1.0});

Creates a box CoreObject with the specified size and color.

createPlane

CoreObject createPlane(Size2d size, Color color = {1.0, 1.0, 1.0, 1.0});

Creates a plane CoreObject with the specified size and color.

createPyramid

CoreObject createPyramid(Size3d size, Color color = {1.0, 1.0, 1.0, 1.0});

Creates a pyramid CoreObject with the specified size and color.

createSphere

CoreObject createSphere(double radius, unsigned int sectorCount = 36,
                        unsigned int stackCount = 18,
                        Color color = {1.0, 1.0, 1.0, 1.0});

Creates a sphere CoreObject with the specified parameters.

radius

double

The radius of the sphere.

sectorCount

unsigned int

default:"36"

The number of sectors (longitude divisions).

stackCount

unsigned int

default:"18"

The number of stacks (latitude divisions).

color

Color

default:"{1.0, 1.0, 1.0, 1.0}"

The color of the sphere.

Example Usage

Basic CoreObject

// Create a simple cube object
CoreObject cube = createBox({1.0, 1.0, 1.0}, Color::red());
cube.setPosition({0.0, 0.5, 0.0});

// Attach a texture
cube.attachTexture(Texture::fromResourceName("Brick", TextureType::Color));

// Attach shaders
VertexShader vs = VertexShader::fromDefaultShader(AtlasVertexShader::Main);
FragmentShader fs = FragmentShader::fromDefaultShader(AtlasFragmentShader::Main);
vs.compile();
fs.compile();
cube.createAndAttachProgram(vs, fs);

// PBR material values
cube.material.albedo = Color::red();
cube.material.metallic = 0.0f;
cube.material.roughness = 0.6f;
cube.material.ao = 1.0f;

scene.addObject(&cube);

Loading a Model

// Load a 3D model from a resource file
Resource modelResource = Workspace::get().createResource("models/character.obj");
Model myModel;
myModel.fromResource(modelResource);

// Transform the model
myModel.setPosition({0.0f, 0.0f, 0.0f});
myModel.setScale({2.0f, 2.0f, 2.0f});
myModel.setRotation({0.0f, 45.0f, 0.0f});

// Add to window
window.addObject(&myModel);

Instanced Rendering

// Create a base object
CoreObject tree = createBox({0.5, 2.0, 0.5}, Color::green());

// Create multiple instances
for (int i = 0; i < 100; i++) {
    Instance& inst = tree.createInstance();
    inst.setPosition({i * 2.0f, 0.0f, 0.0f});
    inst.setScale({1.0, 1.5 + (rand() % 100) / 100.0, 1.0});
}

window.addObject(&tree);

Compound Object

class Robot : public CompoundObject {
private:
    CoreObject body;
    CoreObject head;
    CoreObject leftArm;
    CoreObject rightArm;
    
public:
    void init() override {
        // Create body
        body = createBox({1.0, 2.0, 0.5}, Color::gray());
        body.setPosition({0.0, 0.0, 0.0});
        addObject(&body);
        
        // Create head
        head = createSphere(0.3);
        head.setPosition({0.0, 1.3, 0.0});
        addObject(&head);
        
        // Create arms
        leftArm = createBox({0.2, 1.0, 0.2}, Color::gray());
        leftArm.setPosition({-0.6, 0.5, 0.0});
        addObject(&leftArm);
        
        rightArm = createBox({0.2, 1.0, 0.2}, Color::gray());
        rightArm.setPosition({0.6, 0.5, 0.0});
        addObject(&rightArm);
    }
    
    void updateObjects(Window &window) override {
        // Animate robot arms
        float time = window.getTime();
        leftArm.setRotation({sin(time) * 30.0, 0.0, 0.0});
        rightArm.setRotation({-sin(time) * 30.0, 0.0, 0.0});
    }
};

Robot robot;
robot.init();
window.addObject(&robot);

Core

Graphics

Physics

Audio

Rendering Backend

Environment

Utilities

​Overview

​CoreObject

​Constructor

​Properties

​Geometry Methods

​attachVertices

​attachIndices

​updateVertices

​Shader and Texture Methods

​attachProgram

​createAndAttachProgram

​attachTexture

​Transform Methods

​setPosition

​move

​setRotation

​setRotationQuat

​rotate

​lookAt

​setScale

​Material and Rendering Methods

​setColor

​makeEmissive

​disableDeferredRendering

​renderColorWithTexture

​renderOnlyColor

​renderOnlyTexture

​Visibility Methods

​show

​hide

​Instancing Methods

​createInstance

​Utility Methods

​clone

​initialize

​updateModelMatrix

​Component Methods

​addComponent

​Material Structure

​CoreVertex Structure

​Instance Structure

​Methods

​Model Class

​Methods

​fromResource

​getObjects

​Transform Methods

​Properties

​CompoundObject Class

​Creating a CompoundObject

​Methods

​init

​initialize

​updateObjects

​addObject

​Transform Methods

​Properties

​Helper Functions

​Primitive Creation

​createBox

​createPlane

​createPyramid

​createSphere

​Example Usage

​Basic CoreObject

​Loading a Model

​Instanced Rendering

​Compound Object

Build docs developers (and LLMs) love

Overview

CoreObject

Constructor

Properties

Geometry Methods

attachVertices

attachIndices

updateVertices

Shader and Texture Methods

attachProgram

createAndAttachProgram

attachTexture

Transform Methods

setPosition

move

setRotation

setRotationQuat

rotate

lookAt

setScale

Material and Rendering Methods

setColor

makeEmissive

disableDeferredRendering

renderColorWithTexture

renderOnlyColor

renderOnlyTexture

Visibility Methods

show

hide

Instancing Methods

createInstance

Utility Methods

clone

initialize

updateModelMatrix

Component Methods

addComponent

Material Structure

CoreVertex Structure

Instance Structure

Methods

Model Class

Methods

fromResource

getObjects

Transform Methods

Properties

CompoundObject Class

Creating a CompoundObject

Methods

init

initialize

updateObjects

addObject

Transform Methods

Properties

Helper Functions

Primitive Creation

createBox

createPlane

createPyramid

createSphere

Example Usage

Basic CoreObject

Loading a Model

Instanced Rendering

Compound Object