Minimal Example

Easy3D / Examples / Minimal Example

The repository ships one example, examples/minimal. Its point is the shape of the API: a real game still drives CNA directly (Game loop, GraphicsDevice, input, …) — Easy3D only helps with the camera, batching, atlases, and debug drawing.

This target only builds when CNA is linked (-DEASY3D_LINK_CNA=ON, or a parent-provided CNA target), because constructing a Camera3D / using CNA math requires CNA's compiled code. See Building & CMake.

The full program

#include <Easy3D/Easy3D.hpp>

#include <iostream>

int main()
{
    std::cout << "Easy3D " << Easy3D::VersionString() << '\n';

    using Vector3 = Easy3D::Camera3D::Vector3;

    // Easy3D helps configure a camera; CNA Matrix values come straight back out.
    Easy3D::Camera3D camera;
    camera.SetPosition(Vector3(0.0f, 3.0f, 8.0f));
    camera.SetTarget(Vector3::Zero);

    const auto view = camera.GetViewMatrix();        // Microsoft::Xna::Framework::Matrix
    const auto projection = camera.GetProjectionMatrix();
    (void)view;
    (void)projection;

    // An orbit camera is just a helper that positions the same Camera3D.
    Easy3D::OrbitCamera orbit;
    orbit.SetDistance(12.0f);
    orbit.SetYaw(0.6f);
    orbit.ApplyTo(camera);

    const Vector3& eye = camera.GetPosition();
    std::cout << "camera eye: (" << eye.X << ", " << eye.Y << ", " << eye.Z << ")\n";

    // A small, CNA-free texture atlas (e.g. Blupi sprite frames).
    Easy3D::TextureAtlas atlas(256, 256);
    atlas.Add("blupi_idle_0", Easy3D::AtlasRect{0, 0, 32, 48});
    const Easy3D::UvRect uv = atlas.GetUv("blupi_idle_0");
    std::cout << "atlas regions: " << atlas.Count()
              << ", blupi_idle_0 UV0: (" << uv.U0 << ", " << uv.V0 << ")\n";

    return 0;
}

What it demonstrates, piece by piece

1. One umbrella header

<Easy3D/Easy3D.hpp> pulls in every public helper: Version, the three cameras, both batches, CubeMesh, TextureAtlas, and DebugDraw.

2. CNA types come straight back out

GetViewMatrix() returns a raw Microsoft::Xna::Framework::Matrix. There is no Easy3D matrix type — the values plug directly into CNA rendering code. The Vector3 alias on Camera3D is a convenience, not a wrapper.

3. Camera rigs position a plain Camera3D

OrbitCamera does not own a camera. It computes an eye position from target + yaw/pitch/distance and pushes it into the Camera3D via ApplyTo(). With the defaults (pitch = 0.3) and the values set here, the printed eye lands at roughly (6.47, 3.55, 9.46).

4. The atlas is CNA-free

TextureAtlas works entirely in plain pixel rectangles and normalized UVs — the printed UV top-left for blupi_idle_0 is (0, 0), and the region's bottom-right works out to (0.125, 0.1875) on a 256×256 atlas.

Building and running it

cmake -S . -B build -DEASY3D_LINK_CNA=ON
cmake --build build
./build/examples/minimal/easy3d_minimal        # path may vary by generator

Expected output (abridged):

Easy3D 0.1.0
camera eye: (6.47308, 3.54624, 9.46168)
atlas regions: 1, blupi_idle_0 UV0: (0, 0)

In the default (headers-only) build the example is not built as an executable — but it is still compile-checked, so API drift is caught either way. See Testing for how that works.

For patterns closer to real game code — spritesheet animation, cube terrain, camera rigs in an update loop — continue to Recipes.