3D グラフィックス API

概要

3D 描画は次の流れで使用します。

Graphics3D を生成して描画先を設定する
Scene3D / Node3D / Mesh3D / Primitive3D を組み立てる
beginRender() → render() → endRender() で 1 フレーム描画する

描画制御

xmc::ClearTarget

beginRender() 時にクリア対象を指定する列挙型です。

xmc::ClearTarget の値
値	説明
xmc::ClearTarget::STACK	内部状態スタックをクリア
xmc::ClearTarget::DEPTH	深度バッファをクリア
xmc::ClearTarget::ALL	全クリア

xmc::RenderFlags3D

3D レンダリングの機能フラグです。

xmc::RenderFlags3D の主な値
値	説明
xmc::RenderFlags3D::VERTEX_COLOR	頂点カラーを使用
xmc::RenderFlags3D::VERTEX_NORMAL	頂点法線を使用
xmc::RenderFlags3D::GOURAUD_SHADING	グーローシェーディング
xmc::RenderFlags3D::LIGHTING	ライティング
xmc::RenderFlags3D::COLOR_TEXTURE	テクスチャカラー
xmc::RenderFlags3D::Z_TEST	深度テスト
xmc::RenderFlags3D::Z_UPDATE	深度バッファ更新
xmc::RenderFlags3D::DEFAULT	標準設定

xmc::ParallelMode3D

並列レンダリングモードです。

xmc::ParallelMode3D の値
値	説明
xmc::ParallelMode3D::NONE	並列化なし
xmc::ParallelMode3D::INTERLACE	インターレース分担
xmc::ParallelMode3D::PIPELINE	パイプライン分担

シーン構築

xmc::createScene3D

xmc::Scene3D xmc::createScene3D();

シーンを生成します。Scene3DClass::rootNodes または addNode() でノードを追加します。

戻り値として空の xmc::Scene3D オブジェクトを返します。複数のルートノードを持つシーンを構築したい場合の起点になります。

xmc::createNode3D

xmc::Node3D xmc::createNode3D(xmc::Mesh3D mesh, xmc::mat4 transform = xmc::mat4::identity());

メッシュとローカル変換行列からノードを生成します。

mesh には描画対象メッシュを指定します。 transform にはノードに適用するローカル変換行列を指定します。

戻り値として xmc::Node3D オブジェクトを返します。子ノードを children に追加することでシーングラフを構築できます。

xmc::createMesh3D

xmc::Mesh3D xmc::createMesh3D(std::vector<xmc::Primitive3D> &&prims);

プリミティブ集合からメッシュを生成します。

prims にはメッシュを構成するプリミティブ列を指定します。戻り値として xmc::Mesh3D を返します。

xmc::createCube / createColoredCube / createSphere

xmc::Mesh3D xmc::createCube(float s = 1.0f, bool uv = true);
xmc::Mesh3D xmc::createColoredCube(float s = 1.0f);
xmc::Mesh3D xmc::createSphere(float radius = 1.0f, int segments = 12, int rings = 6, xmc::colorf col = {1.0f, 1.0f, 1.0f, 1.0f});

定型メッシュを生成します。

createCube() の s は立方体の一辺の長さです。 uv を true にすると UV 座標付きメッシュを生成します。

createColoredCube() は頂点色付き立方体を返します。

createSphere() では radius に半径、segments に経度方向分割数、rings に緯度方向分割数、col に球の基本色を指定します。

いずれも戻り値は xmc::Mesh3D です。

プリミティブとマテリアル

xmc::createPrimitive3D

xmc::Primitive3D xmc::createPrimitive3D(
                xmc::PrimitiveMode mode,
                xmc::Vec3Buffer pos,
                xmc::Vec3Buffer norm,
                xmc::ColorBuffer col,
                xmc::Vec2Buffer uv = nullptr,
                xmc::IndexBuffer idx = nullptr,
                xmc::Material3D mat = nullptr);

1 つの描画プリミティブを生成します。

mode には描画トポロジを指定します。 pos は頂点位置配列、norm は法線配列、col は頂点カラー配列です。 uv はテクスチャ座標、idx はインデックス配列、mat はマテリアルを指定します。

使用しない属性は nullptr を指定できますが、レンダリングフラグやマテリアル設定と整合している必要があります。戻り値は xmc::Primitive3D です。

xmc::createMaterial3D

xmc::Material3D xmc::createMaterial3D();

マテリアルを生成します。

戻り値として、各種見た目設定を書き込むための xmc::Material3D オブジェクトを返します。

xmc::MaterialFlags3D

xmc::MaterialFlags3D の値
値	説明
xmc::MaterialFlags3D::HAS_BASE_COLOR	ベースカラーを有効化
xmc::MaterialFlags3D::DOUBLE_SIDED	両面描画
xmc::MaterialFlags3D::ENVIRONMENT_MAPPED	環境マップ反射

xmc::Material3DClass の主なメンバー

xmc::Material3DClass の主なメンバー
型	メンバー	説明
xmc::MaterialFlags3D	flags	マテリアルフラグ
xmc::colorf	baseColor	ベースカラー
xmc::Sprite	colorTexture	カラーテクスチャ
xmc::VertexShader *	vertexShader	頂点シェーダ

属性バッファ

xmc::Vec2Buffer xmc::createVec2Buffer(int size, XmcHeapCap caps = XMC_HEAP_CAP_SPIRAM);
xmc::Vec2Buffer xmc::createVec2Buffer(xmc::vec2 *data, int size, bool autoFree = false);

xmc::Vec3Buffer xmc::createVec3Buffer(int size, XmcHeapCap caps = XMC_HEAP_CAP_SPIRAM);
xmc::Vec3Buffer xmc::createVec3Buffer(xmc::vec3 *data, int size, bool autoFree = false);

xmc::ColorBuffer xmc::createColorBuffer(int size, XmcHeapCap caps = XMC_HEAP_CAP_SPIRAM);
xmc::ColorBuffer xmc::createColorBuffer(xmc::colorf *data, int size, bool autoFree = false);

xmc::IndexBuffer xmc::createIndexBuffer(int size, XmcHeapCap caps = XMC_HEAP_CAP_SPIRAM);
xmc::IndexBuffer xmc::createIndexBuffer(uint16_t *data, int size, bool autoFree = false);

頂点属性配列を生成します。

サイズ指定版では指定要素数のバッファを新規確保して返します。 caps には確保先 RAM の特性を指定します。

ポインタ指定版では既存配列を属性バッファとしてラップします。 data は配列先頭、size は要素数です。 autoFree を true にするとオブジェクト破棄時に data が自動解放されます。

Graphics3D

xmc::createGraphics3D

xmc::Graphics3D xmc::createGraphics3D(int width, int height, uint32_t stackSize = 16);

3D 描画コンテキストを生成します。

width, height には描画先サイズをピクセル単位で指定します。 stackSize は変換状態を保持するスタック深さです。

戻り値として xmc::Graphics3D オブジェクトを返します。

setTarget

void xmc::Graphics3DClass::setTarget(xmc::Sprite target);
void xmc::Graphics3DClass::setTarget(xmc::Sprite target, xmc::Rect viewport);

3D 描画先 Sprite を設定します。

target には描画先 Sprite を指定します。 viewport 指定版では、Sprite 内の描画領域を矩形で指定できます。ビューポート省略版では Sprite 全体が描画領域になります。

setParallelMode / getParallelMode

void xmc::Graphics3DClass::setParallelMode(xmc::ParallelMode3D mode);
xmc::ParallelMode3D xmc::Graphics3DClass::getParallelMode() const;

並列レンダリングモードを設定・取得します。

mode には xmc::ParallelMode3D の値を指定します。 getParallelMode() は現在の並列レンダリングモードを返します。

setFlags / enableFlags / disableFlags

void xmc::Graphics3DClass::setFlags(xmc::RenderFlags3D flags);
void xmc::Graphics3DClass::enableFlags(xmc::RenderFlags3D flags);
void xmc::Graphics3DClass::disableFlags(xmc::RenderFlags3D flags);

レンダリング機能フラグを設定します。

setFlags() はフラグ全体を置き換えます。 enableFlags() と disableFlags() は指定したフラグだけを個別に有効化・無効化します。

setBlendMode

void xmc::Graphics3DClass::setBlendMode(xmc::BlendMode mode);

ブレンドモードを設定します。 mode には xmc::BlendMode の値を指定します。

setEnvironmentLight / setParallelLight

void xmc::Graphics3DClass::setEnvironmentLight(const xmc::colorf &color);
void xmc::Graphics3DClass::setParallelLight(const xmc::vec3 &dir, const xmc::colorf &color);

ライティング条件を設定します。

setEnvironmentLight() は環境光の色を設定します。 setParallelLight() は平行光源の方向 dir と色 color を設定します。

setProjection / setOrthoProjection / setPerspectiveProjection

void xmc::Graphics3DClass::setProjection(const xmc::mat4 &mat);
void xmc::Graphics3DClass::setOrthoProjection(float left, float right, float bottom, float top, float near = 0.01f, float far = 100.0f);
void xmc::Graphics3DClass::setPerspectiveProjection(float fovY, float aspect, float near = 0.01f, float far = 100.0f);

投影行列を設定します。

setProjection() は投影行列を直接設定します。 setOrthoProjection() は平行投影、setPerspectiveProjection() は透視投影を簡易に設定する補助関数です。

setViewMatrix / lookAt

void xmc::Graphics3DClass::setViewMatrix(const xmc::mat4 &mv);
void xmc::Graphics3DClass::lookAt(const xmc::vec3 &eye, const xmc::vec3 &focus, const xmc::vec3 &up);

ビュー行列を設定します。

setViewMatrix() はビュー行列を直接設定します。 lookAt() は視点 eye、注視点 focus、上方向 up からビュー行列を生成して設定します。

pushState / popState

void xmc::Graphics3DClass::pushState();
void xmc::Graphics3DClass::popState();

変換状態スタックを保存・復元します。階層構造をたどりながら個別の変換を適用したい場合に使用します。

loadIdentity / loadMatrix / transform

void xmc::Graphics3DClass::loadIdentity();
void xmc::Graphics3DClass::loadMatrix(const xmc::mat4 &m);
void xmc::Graphics3DClass::transform(const xmc::mat4 &t);

現在のモデル変換行列を設定します。

loadIdentity() は単位行列へ初期化します。 loadMatrix() は行列を直接設定します。 transform() は現在行列に変換行列を乗算します。

translate / rotate / scale

void xmc::Graphics3DClass::translate(const xmc::vec3 &t);
void xmc::Graphics3DClass::translate(float x, float y, float z);
void xmc::Graphics3DClass::rotate(const xmc::quat &q);
void xmc::Graphics3DClass::rotate(float pitch, float yaw, float roll);
void xmc::Graphics3DClass::rotate(const xmc::vec3 &axis, float angle);
void xmc::Graphics3DClass::scale(const xmc::vec3 &s);
void xmc::Graphics3DClass::scale(float s);

現在のモデル変換に平行移動、回転、拡大縮小を適用します。オーバーロードによりベクトル指定と成分指定の両方を使用できます。

beginRender / endRender

void xmc::Graphics3DClass::beginRender(xmc::ClearTarget target = xmc::ClearTarget::ALL);
void xmc::Graphics3DClass::endRender();

1 フレーム分の 3D 描画を開始・終了します。

beginRender() の target にはクリア対象を指定します。通常は既定値の xmc::ClearTarget::ALL を使用します。

render

void xmc::Graphics3DClass::render(const xmc::Scene3D &scene);
void xmc::Graphics3DClass::render(const xmc::Node3D &node);
void xmc::Graphics3DClass::render(const xmc::Mesh3D &mesh);
void xmc::Graphics3DClass::render(const xmc::Primitive3D &prim);

シーンまたは描画要素をレンダリングします。

大きなシーン全体を描く場合は Scene3D を、個別に制御したい場合は Node3D、Mesh3D、Primitive3D を直接渡します。 beginRender() と endRender() の間で呼び出します。