Cogs Native Bridge Interface

Description on using the Cogs.Native functionality for Entities, Components and Resources in C++ application.

Cogs.Native does not contain functionality to set up GUI elements like 3D window etc.

TOC

• Cogs Native Bridge Interface
  • TOC
  • Creating and Deleting Cogs Entities
  • Accessing Components
    • Adding extra Components
  • Accessing and setting Component Fields
  • Using Cogs Bridge Functions
  • Using Resources

Creating and Deleting Cogs Entities

Each Entity is defined in one header file with same name as the entity. For Entities in Cogs Extensions use "Entities/ExtensionName/EntityName.h".

#include "Entities/Cube.h"

void doSomething(BridgeContext* context)
{
    // Create new Entity.
    Cogs::Native::Cube cube = Cogs::Native::Cube(context, "Cube");

    // Access existing entity, for example loaded from Scene
    Cogs::Native::Cube cubeExisting = Cogs::Native::Cube(context, "CubeExisting", false);
}
Copy

Note that the created Cube is not automatically destroyed when the 'cube' object goes out of scope.

Deleting entity:

#include "Entities/Cube.h"

void createAndDelete(BridgeContext* context)
{
    // Create new Entity.
    Cogs::Native::Cube cube = Cogs::Native::Cube(context, "Cube");
    cube.release();

    // Access existing entity, for example loaded from Scene
    Cogs::Native::Cube cubeExisting = Cogs::Native::Cube(context, "CubeExisting", false);

    // Does nothing. Assumes accessing existing should note be deleted.
    cubeExisting.release();

    // Mark ownership, then release.
    cubeExisting.takeOwnership();
    cubeExisting.release();
}
Copy

Accessing Components

All pre-defined components are stored in a shared_pointer in the entity. E.g. TransformComponent:

#include "Entities/Cube.h"

void doSomething(Cogs::Native::Cube* cube)
{
    => cube->transformComponent
}
Copy

It is possible to access a defined component in the entity using:

#include "Entities/Cube.h"

//! class EntityBase is the root of all Entities.
void doSomething(Cogs::Native::EntityBase* cube)
{
    auto xc = cube->getComponent();
    if (xc) {

    }
}
Copy

Adding extra Components

Example: Add Cogs predefined navigation:

#include "Entities/Camera.h"
#include "Components/OrbitingCameraController.h"

//! class EntityBase is the root of all Entities.
void setupNavigation(BridgeContext* context)
{
    Cogs::Native::Camera camera(context, "Camera", false);

    // Create and add Component to entity.
    auto cameraController = camera.createComponent();
}
Copy

Accessing and setting Component Fields

All component fields are defined using a TypedField<T> object. This object has automatic conversion operator to get field value and to set field value.

#include "Entities/Cube.h"

//! class EntityBase is the root of all Entities.
void doSomething(Cogs::Native::Cube* cube)
{
    // Recommended: Get field value:
    glm::vec3 pos = cube->transformComponent->position;

    // Set field value:
    cube->transformComponent->position = glm::vec3(1, 2, 3);

    // Possible: Get field value using the .value() method:
    auto pos = cube->transformComponent->position.value();

    // Can be used to Copy field value to another component:
    cube2->transformComponent->position = cube->transformComponent->position.value();

    // ERROR Failing: returns a copy of the TypedField. Will assert.
    auto pos = = cube->transformComponent->position;
}
Copy

Using Cogs Bridge Functions

Cogs.Native does not fully hide the Cogs Bridge like Cogs.Net and Cogs.js does. Cogs.Bridge functions are often used to load scenes, crete texture etc. The Context is usually the first parameter. For Resource loading there is usually an int flags parameter. This flags is an enum:

#include "Enums/AssetLoadFlags.h"

//! Load scene(asset) from given C-string.
void loadResource(BridgeContext* context, const char* sceneDef)
{
    ::loadAssetFromString(context, sceneDef, NoEntity, int(AssetLoadFlags::None));
}
Copy

Using Resources

Resource handling involves a mixture of wrapper classes and Cogs Bridge usage. See Cogs.Demos for examples of how to load and use resources. The wrapper classes are used when setting and getting Component Fields that are resource handles.