webg

最小描画

本章では、WebgAppを使って立方体を一つ表示します。まず画面に形が現れ、回転し、視点を操作できる状態を作り、その後で初期化、形状の準備、配置、更新のつながりを確認します。

WebgAppは描画先やカメラ、フレーム更新をまとめて準備します。利用者は表示したい形状と、その動かし方へ集中して作り始められます。土台の仕組みを詳しく調べる際は、後半の低水準構成との比較から37章へ進めます。

この章の読み方

この章を読む前に必要な知識

02章の実行環境と03章の座標の基本を確認してください。コードはリポジトリのuser/minimum/minimum.htmlへ保存する配置を想定しています。

初回に読む範囲

立方体を表示する例を実行し、初期化、形状の確定、Nodeへの配置、経過時間を使う更新を順に確認してください。

必要になったときに読む範囲

描画を直接制御する場合は低水準構成との比較と37章を参照します。アプリケーションの機能を追加する場合は05章、カメラを調整する場合は06章へ進みます。

この章を終えた時点でできること

WebgAppで立方体を表示し、時間に合わせて回転させ、マウスで視点を操作できます。

まず立方体を表示する

リポジトリのルートで02章のHTTPサーバーを起動します。次の内容をuser/minimum/minimum.htmlへ保存し、http://localhost:8000/user/minimum/minimum.htmlを開いてください。二階層下のフォルダからライブラリを読むため、importのパスは../../webg/です。

このHTMLは、キャンバスとJavaScriptを一つにまとめた実行例です。WebgAppがキャンバスを描画先として使い、初期化が完了した後に形状とカメラを準備します。

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>webg minimum</title>
</head>
<body style="margin:0; overflow:hidden">
  <canvas id="canvas"></canvas>
  <script type="module">
import WebgApp from "../../webg/WebgApp.js";
import Shape from "../../webg/Shape.js";
import Primitive from "../../webg/Primitive.js";

const app = new WebgApp({
  messageFontTexture: "../../webg/font512.png",
  clearColor: [0.1, 0.15, 0.1, 1.0],
});
await app.init();

const orbit = app.createOrbitEyeRig({
    target: [0.0, 0.0, 0.0],
    distance: 8.0,
    yaw: 24.0,
    pitch: -12.0,
    minDistance: 4.0,
    maxDistance: 18.0,
    wheelZoomStep: 1.0
});

const shape = new Shape(app.getGPU());
shape.applyPrimitiveAsset(Primitive.cube(2.0, shape.getPrimitiveOptions()));
shape.endShape();

shape.setMaterial("smooth-shader", {
  has_bone: 0,
  use_texture: 0,
  color: [1.0, 0.5, 0.3, 1.0]
});

const obj = app.space.addNode(null, "obj");
obj.addShape(shape);

app.start({
  onUpdate: ({ deltaSec }) => {
    obj.rotateY(30.0 * deltaSec);
    obj.rotateX(15.0 * deltaSec);
  }
});
  </script>
</body>
</html>

緑がかった背景にオレンジ色の立方体が表示され、ゆっくり回転します。ドラッグで視点を周回し、ホイールで距離を変えられます。形状と動きが確認できたら、color、distance、回転速度を一つずつ変え、どの値が画面へ影響するかを確かめましょう。

既存の教材ページはWebgAppの実行例で開けます。教材ページには固定サイズのキャンバスや操作説明が付いています。ここに示したHTMLは、ウィンドウ全体で表示する基本構成です。

統合版で同じ例を動かす

上のHTMLをuser/minimum/minimum.htmlに置く場合は、3つのimportを 次のコードへ置き換えます。初期化・形状・更新のコードは共通です。

import { WebgApp, Shape, Primitive }
  from "../../lib/webg.core.min.js";

フォントは上の例のmessageFontTexture: "../../webg/font512.png"を使います。 統合する対象はJSなので、素材のURLはアプリの配置に合わせて指定します。 同じHTTPページで立方体の回転・ドラッグ・ホイール操作を確認してください。 詳しい配置は02章、既存サンプルの自動変換は付録C_統合版の利用.mdで説明します。

初期化から配置までを読む

new WebgApp()で背景色やフォント画像の場所を指定し、await app.init()で描画の準備完了を待ちます。その後のapp.getGPU()は、形状を描画用データへ変換するために使います。初期化と形状の作成をこの順にすると、準備が済んだ描画先へデータを登録できます。

Primitive.cube(2.0, ...)は一辺2の立方体のデータを生成します。Shapeへ取り込んだ後のendShape()で、頂点と面のデータをGPUの描画用バッファへ確定します。続くsetMaterial()では、この例の表面色を指定します。材質の考え方は07章で詳しく説明します。

形状を置く場所はNodeが表します。app.space.addNode(null, "obj")でシーンへ配置し、addShape(shape)で見た目を取り付けます。形状と配置を分けると、同じ形を使いながら位置や向きを個別に管理できます。複数モデルの配置は08章で扱います。

カメラと経過時間を使う

周回カメラのtargetは見る位置、distanceはその位置からの距離です。立方体は原点にあるため、目標も[0, 0, 0]に揃えています。yawとpitchは初期の視点方向、minDistanceとmaxDistanceはズームの範囲を決めます。

app.start()を呼ぶとフレーム更新と描画が始まります。onUpdateは描画の前に呼ばれ、deltaSecには前のフレームからの経過秒数が入ります。rotateY(30.0 * deltaSec)は毎秒30度の回転です。経過時間を掛けることで、画面の更新頻度が変わっても同じ時間でほぼ同じ角度だけ進みます。

表示結果を確認する

表示される形、色、位置、動きを分けて確認すると、設定を調整しやすくなります。形はPrimitive、色はマテリアル、位置はNode、見える範囲はカメラへ対応します。

画面が表示されるまでの準備は、app.init()の完了、endShape()による形状の確定、addShape()による配置、app.start()による更新開始の順です。表示が止まった場合は、ブラウザの開発者コンソールで例外とファイルの読み込み結果を確認し、この順序で準備済みの範囲を追います。

低水準構成で土台を確かめる

WebgAppの内部では、Screenが描画先、Spaceがシーン、Nodeが配置、Shapeが形状と材質を扱います。標準構成ではこれらの準備と毎フレームの描画をWebgAppへまとめています。

描画先や処理順を自分で制御する場合は、Screenとシェーダーを初期化し、視点とShapeを用意して、画面の初期化、シーンの描画、表示を順に呼びます。低水準の実行例では、この順序を確認できます。

GPUDevice、バッファ、パイプライン、描画コマンドの対応は37章で説明します。最初に標準構成の表示結果を知っておくと、低水準の各処理が画面のどの段階を担当するかを理解しやすくなります。

まとめ

WebgAppを初期化し、形状を確定してNodeへ取り付け、onUpdateで動かすことで、最初の3D画面を作れます。次の05章では、この構成へ入力、表示、更新処理を追加する方法を学びます。