# 実行環境

本章では、`webg`のサンプルと自作アプリケーションを同じ条件で実行するために、ローカルサーバーとWebGPU対応ブラウザを準備します。
ページが開かない場合は、WebGPU API（WebGPUの機能をJavaScriptから呼び出す仕組み）への対応、セキュアコンテキスト、ファイルの取得結果を順に確認し、コードの不具合と実行環境の問題を区別できるようにします。

## この章の読み方

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

JavaScriptの基本的な実行方法と、ファイルやフォルダーを扱う操作を知っていると読みやすくなります。

### 初回に読む範囲

WebGPU対応ブラウザ、ローカルサーバー、最初のサンプルを開く手順を読んでください。

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

セキュアコンテキスト、GPU（Graphics Processing Unit：画像処理装置）の機能、キャッシュ、ネットワーク実行で問題が起きたときは該当節を参照してください。

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

webgのサンプルと自分のHTMLを正しい環境で起動し、環境の問題とアプリの問題を切り分けられます。

## 必要な実行環境を確認する

`webg`を実行するには、WebGPUに対応したブラウザと、HTMLやJavaScript、画像、モデルを配信するWebサーバーが必要です。
最初にセキュアコンテキスト上で`navigator.gpu`が利用できることを確認し、次にローカルサーバーからサンプルを開いてください。
ファイルをブラウザで直接開く方法では、モジュールやアセットの読み込みがブラウザの安全上の制限を受けます。

本章では、`webg` を手元のマシンに配置し、サンプルや`unittest`を実際に起動するまでの手順を解説します。
01章でプロジェクトの全体像を把握し、04章以降でアプリケーションの組み立て方を学ぶための前提として、まずは「正しく動作する実行環境」を整えます。

`webg` の利用においては、ライブラリをパッケージとしてインストールするのではなく、リポジトリをそのまま配置して利用する運用を基本としています。
また、サンプルや`unittest`を実行する際は、ファイルをブラウザで直接開かず、ローカルサーバーを経由してアクセスしてください。

もし、実装が正しいにもかかわらずファイルを直接開いてアセットの読み込みに失敗した場合、「WebGPUのコードに問題があるのか」「ブラウザが未対応なのか」「パスの設定が間違っているのか」という切り分けが困難になります。
そのため、まずは「サーバーの問題」と「ブラウザのWebGPU対応状況」を明確に分けて考えることが重要です。

## ローカルサーバーが必要な理由

`webg`のサンプルは、HTML、JavaScript、JSON、画像、モデルを組み合わせて構成します。
`main.js`や`webg/*.js`といったスクリプトに加え、JSON、テクスチャ、glTF（GL Transmission Format：3Dシーン交換形式）、GLB（glTFのバイナリ形式）、Colladaといった外部アセットを組み合わせて構成されています。

ブラウザでこれらのファイルを読み込む際は、同一オリジンポリシー（Same-Origin Policy：SOP）と、オリジン間リソース共有（Cross-Origin Resource Sharing：CORS）が重要です。
同一オリジンポリシーは、ページがアクセスできるリソースを、プロトコル、ホスト、ポートがすべて一致する同一オリジンへ制限する仕組みです。

ファイルをブラウザで直接開いた場合（`file://` プロトコル）、通常のHTTPページとはオリジンの扱いが異なり、多くのブラウザでESモジュールの `import` や `fetch()` によるアセット読み込みが制限されます。
制限の詳細はブラウザによって異なりますが、ページ自体は表示できても、モジュール、テクスチャ、モデルの読み込みで失敗し得ます。
実行条件をそろえるため、本書ではローカルHTTPサーバーを標準経路とします。

具体的に`webg`内で`fetch()`を直接利用している主なファイルは次のとおりです。
* `webg/Texture.js`
* `webg/ModelAsset.js`
* `webg/SceneAsset.js`
* `webg/Gltf.js`
* `webg/AudioSynth.js`
* `webg/util.js`

これらを正常に動作させるには、`http://localhost:8000/` のようなローカルサーバーを立て、HTTP配信経由でアクセスする必要があります。
これにより、相対パスによるモジュールの読み込みやアセットの取得が、標準的なWebページと同様に動作するようになります。

## ファイルの配置手順

リポジトリ全体を同じ相対パスのまま配置すると、サンプル、書籍のサンプル、コアモジュール、アセットの参照関係を変更せずに実行できます。
必要なフォルダーだけを切り出すより、教材と実装を同じ構成で比較でき、更新時にも差分を追いやすくなります。
まずは`webg`リポジトリを手元に用意してください。

### `git clone` を利用する場合
更新履歴を管理し、最新の状態を維持したい場合に推奨される方法です。

```bash
git clone https://github.com/jun-mizutani/webg.git
cd webg
```

### フォルダコピー（zip）を利用する場合
GitHubのリポジトリからzipファイルをダウンロードし、展開して配置してください。
（ダウンロード先: https://github.com/jun-mizutani/webg/archive/refs/heads/main.zip）

展開した`webg`フォルダ内に、例えば`my_webg`という作業用フォルダを作成し、その中でプロジェクトを構築します。`my_webg/main.js`からコアを読むパスは`../webg/WebgApp.js`です。`samples/high_level/`のように二階層下へ置く場合は`../../webg/WebgApp.js`になるため、コピー先の深さに合わせてimportを調整します。

```text
webg/
  book/
  samples/
  unittest/
  webg/
  my_webg/
```

なお、`samples/` や `webg/` フォルダだけを切り出すと相対パスが崩れるため、必ずリポジトリのルートディレクトリを保持したまま運用してください。

## 統合版を読み込む

webgは、`webg/`の個別モジュール版と、`lib/webg.core.min.js`の統合版を選べます。
本書の各章は、定義元を調べやすい個別モジュール版を基本にしています。
統合版でもクラスとメソッドの使い方は共通です。

統合版を使う場合は、次のようにクラス名を名前付きimportで取り出します。
リポジトリのルートにある`main.js`から読み込む例です。

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

`WebgApp`を別の名前で使う場合は、`WebgApp as App`と指定できます。
HTML内のコードは`<script type="module">`に置き、外部JSのimportパスは
そのJSからの相対パスに合わせます。実行には本章のHTTPサーバーを使います。

`lib/webg.core.js`はコメントを保持する版です。
`.map`ファイルは、開発者ツールで統合後のコードから元ソースの行へ進むために使います。
ソースマップを使う場合は、`lib/`と`webg/`の相対配置を保持します。
アプリの実行にはJSを読み込み、画像・モデル・フォントはそれぞれのURLで用意します。

既存サンプルを切り替える方法は`付録C_統合版の利用.md`を参照してください。
同じアプリ内では、コアの読み込みを個別版か統合版のどちらかへ揃えます。
共通のクラスとモジュール状態を使うため、共有JSと動的importも合わせて確認します。

## サンプルの実行

付属サンプルは、環境が正しく整ったかを自作コードより先に確認するために使います。
既知のコードが動けば、以後の問題をブラウザやサーバーではなく、自作部分へ絞り込めます。
後述するローカルサーバーを起動してから、ブラウザで以下のURLへアクセスしてください。

```text
http://localhost:8000/samples/
```

## 実行環境の使い分け

リポジトリ内のファイルには、「直接開いても問題ないもの」と「サーバー経由で開くべきもの」があります。

### 直接開いても動作しやすいもの
以下のような静的なページは、主に一覧や説明の表示が目的であり、アセット読み込みやモジュール実行に依存しないため、`file://` で直接開くことが可能です。
* `samples/index.html`
* `unittest/index.html`
* 各種ドキュメントファイル

### HTTPサーバー経由で開くべきもの
以下のような実行系ページは、`<script type="module">` によるESモジュールの利用や、`fetch()` による外部ファイルの読み込み、およびWebGPUの初期化（`navigator.gpu`）に依存しているため、ローカル、LAN内、インターネット上のいずれかのHTTPサーバーから配信してください。
* 最小コードの実行ページ
* `samples/high_level/high_level.html`など、サンプルの実行ページ
* `unittest/*/index.html` の大部分
* `examples/*.html` の大部分

サンプルの`index.html`は説明ページとして使う場合があります。実行する際は`samples/index.html`の実行リンク、または各説明ページの「実行する」リンクから進んでください。

## ネットワーク環境とセキュアコンテキスト

### LAN内のWebサーバーで実行する

LAN内の既存Webサーバー（例: `http://192.168.1.20/webg/`）にリポジトリを配置して実行することも可能です。
この場合もモジュールのインポートや `fetch()` は正常に動作します。

ただし、WebGPUはブラウザによってセキュアコンテキスト（Secure Context） を要求します。
`localhost` は例外的にセキュアな環境として扱われますが、LAN内のIPアドレスやホスト名でHTTP配信した場合、`navigator.gpu` が利用できないことがあります。

LAN内のサーバーでアセットを読み込めても、WebGPUの利用条件が別途必要になる場合があります。
その場合は、配信プロトコルをHTTPSに変更します。
または、動作確認だけを `localhost` で行います。
サーバー設定とWebGPUの対応状況を切り分けてください。

### インターネット上の公開Webサーバーで実行する

インターネット上へ公開する場合も、HTML、ES Module、画像、モデルをHTTPで配信する基本構成はローカルサーバーと同じです。
ここで説明するHTTPS、MIME type、CORS（Cross-Origin Resource Sharing：オリジン間リソース共有）、キャッシュ、セキュリティの制限は、ES Module、`fetch()`、画像、モデル、WebGPUを使う一般のWebページにも共通します。

HTTPSと一般的な静的ファイル配信に対応したホスティングサービスへ、HTML、JavaScript、アセットを同じオリジンから配置すると、HTTPSやJavaScript用MIME typeをサービスの標準設定で利用できます。webgはその配信環境へそのまま配置できます。
まずはローカル環境と同じ相対パスを保って同一オリジンへ配置してください。

以下の項目は、独自Webサーバーを設定する場合、公開後に読み込みエラーが出た場合に、該当する箇所だけを確認するためのものです。

#### HTTPSでページとすべてのリソースを配信する

WebGPUの入口である`navigator.gpu`をセキュアコンテキストで利用する条件は、webgではなくWebGPU API自体に定められたものです。
`localhost`は開発用の例外として安全なコンテキストに扱われますが、インターネット上の公開ページは有効な証明書を持つHTTPSで配信してください。

公開HTMLをHTTPSで配信していても、JavaScript、画像、JSON、GLBなどの一部を`http://`から読み込むと、Mixed Contentとしてブラウザに拒否されることがあります。
HTMLから参照するリソースは、同じHTTPSオリジンか、HTTPSで配信される許可済みの別オリジンへ統一します。

#### 公開URLと相対パスを一致させる

相対importと`fetch()`のURLが公開先のディレクトリ構成を基準に解決されることも、一般的なES ModuleとWebページの動作です。
`webg`もこの標準的な仕組みを使います。
リポジトリを`https://example.com/webg/`のようなサブディレクトリへ配置する場合は、`samples/`、`webg/`、画像、モデルの相対関係を維持してください。

公開サーバーではファイル名の大文字と小文字を区別する構成が一般的です。
ローカル環境で偶然読み込めた`WebgApp.js`と`webgapp.js`のような不一致が、公開後に`404 Not Found`になることがあります。
HTML、import文、`fetch()`へ記載した文字列を、実際のファイル名と一致させます。

存在しないURLをサイト共通の`index.html`へ置き換えてStatus `200`で返す設定にも注意が必要です。
この設定でJavaScriptやJSONのURLを間違えると、`404`ではなくHTMLが返り、MIME type error、`Unexpected token '<'`、JSON parse errorとして現れます。
NetworkパネルでRequest URL、Status、Content-Type、Responseを確認し、要求したファイルそのものが返っていることを確かめてください。

#### ES Moduleを正しいMIME typeで配信する

ES Moduleとして読み込む`.js`ファイルにJavaScript用MIME typeが必要なことは、すべてのES Moduleに共通するブラウザの規則です。
webg固有のContent-Typeを追加する必要はなく、通常のJavaScriptと同じ`text/javascript`などを使用します。
ファイルの拡張子が`.js`でも、サーバーはJavaScript用のMIME type（通常は`text/javascript`）を返す必要があります。`text/plain`や`text/html`が返ると、ブラウザはモジュールの実行を止めます。

```text
Content-Type: text/javascript
```

HTML、JSON、画像、フォント、モデルについても、サーバーが各形式に合うContent-Typeを返すよう設定します。
特に、拡張子を認識しないホスティングサービスや独自の静的ファイル配信設定では、NetworkパネルのResponse Headersを確認してください。

#### 公開時のキャッシュ方針を決める

公開WebサーバーやCDNで、ブラウザだけでなく中継キャッシュにも応答が保存されることは、一般のWebページと同じです。
HTMLは新しいJavaScriptのURLを利用者へ伝える入口なので、更新確認を行いやすい短いキャッシュまたは再検証を使います。
内容hashやversionをURLへ含めたJavaScript、画像、モデルは、内容が変わればURLも変わる前提で長くキャッシュできます。

同じURLの内容を置き換える運用では、HTMLとJavaScriptを再検証できる`Cache-Control`を設定し、必要に応じてCDNのキャッシュ削除または無効化を行います。更新の通知はHTTPキャッシュ制御と配信基盤で管理し、source内のURLは安定した参照先として保ちます。
公開直後は自分のブラウザだけで判断せず、Networkパネルで最終的なRequest URL、Status、Response Headers、Response本文を確認してください。

## ローカルサーバーの起動方法

リポジトリのルートディレクトリをカレントディレクトリとして、以下のコマンドを実行してください。

```bash
cd /path/to/webg
```

### OSごとの起動コマンド例

どのコマンドも目的は同じで、リポジトリのルートをHTTPで配信します。
利用中のOSと導入済みのランタイムに合わせて、実行しやすい方法を一つ選びます。一つのサーバーでリポジトリ全体を配信できます。

#### Mac / Linux
Python 3の簡易サーバーを利用する方法が最も手軽です。

```bash
# Python 3 を利用する場合
python3 -m http.server 8000

# Node.js (npx) を利用する場合
npx http-server . -p 8000

# PHP を利用する場合
php -S 127.0.0.1:8000
```

`npx`は、Node.jsと`http-server`を取得済みの環境で利用できます。
`npx`が未取得のパッケージを自動取得する設定ではネットワーク接続が必要です。
外部接続を使わずに試す場合は、取得済みのPython 3またはPHPによるローカルサーバーを使います。

#### Windows
Windows環境では、Pythonランチャー（`py`）の利用が簡単です。

```powershell
# Python Launcher を利用する場合
py -m http.server 8000

# Python 3 を直接利用する場合
python -m http.server 8000

# Node.js (npx) を利用する場合
npx http-server . -p 8000
```

サーバーを起動後、ブラウザで以下のURLにアクセスしてください。
`http://127.0.0.1:8000/samples/index.html` または `http://localhost:8000/samples/index.html`

※ 他のアプリケーションとポートが衝突する場合は、`8000` の部分を `9000` など任意の番号に変更してください。

## 推奨される確認手順

環境構築後、いきなり複雑なサンプルを動かすのではなく、以下の順序で段階的に確認することをお勧めします。
これにより、問題が発生した際の切り分けが容易になります。

1. `samples/index.html` を開く
   サーバーが正常に動作し、ファイルが配信されているかを確認します。
2. `low_level` サンプルで最小描画を確認する
   低水準な最小構成で、WebGPUの描画が機能するかを確認します。
3. `high_level` サンプルで `WebgApp` の構成を確認する
   高水準な標準構成で、アプリ基盤が動作するかを確認します。
4. `scene_model_yaml`サンプルでSceneYAMLとModelYAMLの読み込みを確認する
   外部アセットの読み込みとシーン構成が正しく動作するかを確認します。
5. 目的に応じた詳細サンプル（`sound`, `bloom`, `dof` など）へ進む

## トラブルシューティング

ローカル、LAN内、インターネット上のいずれのサーバーでも、動作しない場合はまず「サーバーの問題」と「ブラウザのWebGPU対応状況」を切り分けて確認してください。

### サーバーとWebGPUの問題を切り分ける

* サーバーの問題が疑われる場合
  - URLで一覧ページが表示されるか。
  - ブラウザのコンソールに `404 Not Found` や `CORS error` が出ていないか。
  - リポジトリの途中階層（例: `samples/scene/`）をサーバーのルートにしていないか。
* WebGPUの対応状況が疑われる場合
  - ブラウザのコンソールで `navigator.gpu` が `undefined` になっていないか。
  - `webg/Screen.js` がWebGPUの初期化に失敗していないか。

最小構成である `low_level` サンプルまで戻って動作を確認することで、問題が「アセット読み込み」にあるのか、「WebGPUの実行環境」にあるのかを迅速に特定できます。

### ブラウザキャッシュの問題

ブラウザキャッシュは、一度取得したHTML、JavaScript、画像などの情報をブラウザ内へ保存し、同じURLを再び開いたときに保存済みの情報を再利用する仕組みです。
毎回すべてのファイルをサーバーから転送しないため、ページの表示を速くし、通信量を減らせます。
キャッシュ自体は問題ではなく、通常の閲覧と公開アプリケーションに必要な機能です。

一方で、開発中にHTML、JavaScript、画像ファイルの内容を変更してもURLが同じままなので、ブラウザが保存済みの応答を再利用し、変更したJavaScriptやHTMLが使用されないことがあります。
WGSLをJavaScript内の文字列として定義している場合は、古いJavaScriptのキャッシュに古いWGSLも含まれます。
WGSLを別ファイルとして取得する場合も、そのURLの古い応答が残る可能性があります。

この状態では、修正したはずの表示が変わらない、削除したログが出る、新しく追加したメソッドが存在しない、JavaScriptとライブラリの世代がずれてWebGPU validation errorが出る、といった現象が起こります。
コードを再修正する前に、ブラウザが実際に読み込んだファイルが編集後の内容かを確認してください。

#### 再読み込みとNetworkパネルで確認する

まずキャッシュを使わない再読み込みを行います。
表示が変わらない場合は、Networkパネルで対象ファイルのRequest URL、Status、転送元、Response本文を確認します。
それでも編集後の内容が取得できない場合に、Service Workerやサイトデータの影響を調べます。

通常のReloadでは保存済みの応答を再利用する場合があるため、最新ファイルを確認するときはキャッシュを使わないハードReloadを行います。
ハードReloadには、次の二つの方法があります。

1. Shiftキーを押しながらブラウザのReloadボタンを押す
2. 開発者ツールを開き、Networkパネルの`Disable cache`を有効にしてからページをReloadする

ブラウザによって項目名や操作方法は異なります。
二番目の方法では、開発者ツールを開いている間だけキャッシュを使わないため、通常の閲覧用キャッシュを恒久的に無効にせず、Networkパネルで取得結果も続けて確認できます。

どのファイルが使われたかを確認するときは、次の順序でNetworkパネルを読みます。

1. Networkパネルの以前の通信記録を消去する
2. `Disable cache`を有効にしたままページを再読み込みする
3. Filterへ、変更した`main.js`や`WebgApp.js`などのファイル名を入力する
4. Request URLが、現在起動しているHTTPサーバーの想定したURLであることを確認する
5. Statusが`200`で、SizeまたはTransferredに`memory cache`や`disk cache`と表示されていないことを確認する
6. 通信行を選択してResponseを開き、変更した関数名、コメント、数値などが応答本文へ含まれていることを確認する

Status `304`は、ブラウザがサーバーへ更新の有無を問い合わせ、サーバーが変更なしと答えたため、保存済みの応答本文を再利用したことを表します。
最新ソースそのものを確認する調査では、キャッシュを無効にした再読み込みを行い、Status `200`のResponseへ変更内容が含まれることを確認してください。

対象ファイルがNetworkパネルに現れない場合は、開いているHTMLがそのファイルをimportしているかを確認します。
Request URLが別のサーバーや別のディレクトリを指す場合は、HTMLのimport先、ブラウザで開いたURL、HTTPサーバーを起動したディレクトリを確認します。
Responseが変更前の内容なら、ブラウザキャッシュだけでなく、HTTPサーバーが参照しているファイル自体が編集対象と同じものかも確認してください。

#### Module URLへ手動のcache識別子を付けない

webgのsource、sample、unittestでは、JavaScriptを常にファイル本来の相対URLで読み込みます。HTMLのentry moduleとJavaScriptからのimportは、次のようにqueryを持たないURLへ統一してください。

```html
<script type="module" src="./main.js"></script>
```

```js
import WebgApp from "../../webg/WebgApp.js";
import Shape from "../../webg/Shape.js";
```

この規則はmoduleの同一性を保つためのものです。ES Moduleでは、queryを含むURL全体が一つのmoduleを識別します。同じ`Shape.js`を指しているつもりでも、一方のURLだけへcache更新用queryを追加すると、browserは別moduleとして評価します。その結果、class、prototype、static field、module内のregistryやcacheも別々に作られます。

WebgAppは初期化したshaderをShape classへ設定します。WebgApp内部とアプリケーション側が同じURLからShapeを読み込むと、Shape class、`instanceof`による型判定、singletonとして共有するGPU resource、module単位の生成済みpipeline cacheを同じ実体で扱えます。異なるURLから読み込んだ場合は、読み込み成功後にshader設定や型判定の食い違いとして現れるため、URLを統一して原因を追いやすくします。

開発中に古いJavaScriptが疑われる場合は、source URLを固定したまま、前節の手順でNetworkパネルの`Disable cache`を有効にしてReloadします。Request URL、Status `200`、転送元、Response本文を確認すれば、実行されたsourceが編集後の内容かを判断できます。更新確認にはブラウザのキャッシュ制御を使い、source URLへ手動query、現在時刻、乱数を追加する方法は避けます。これにより、module identityを保ったまま更新漏れを調べられます。

公開時もsource内のimport URLを固定します。同じURLを更新する構成では、HTMLとJavaScriptを再検証する`Cache-Control`とCDNの無効化を使用します。将来build systemを導入して内容hash付きのファイル名を生成する場合は、buildが依存graph全体のimport先を同時に書き換え、同一moduleを常に一つの生成URLへ統一します。version管理はbuildまたはサーバーのキャッシュ制御へ集約します。

APIの検索条件など、アプリケーション本来の入力にはquery parameterを使えます。ここで管理する対象は、同じJavaScript sourceを別URLに見せるためだけの手動cache識別子です。

#### iPhoneのSafariでキャッシュを消去する

iPhoneのSafariで通常の再読み込みを行っても古い内容が残る場合は、Safariを閉じて開き直したうえで、対象ページを再度確認します。
次に、使用中のiOSで対象サイトだけのデータを削除できる項目があるか確認します。
iOSのバージョンによってメニュー名や利用できる削除方法は異なります。
対象サイトだけを削除できず、それでも更新されない場合に限り、「設定」から「アプリ」へ進み、「Safari」を選び、「履歴とWebサイトデータを消去」を最後の手段として実行します。

```text
設定 / アプリ / Safari / 履歴とWebサイトデータを消去
```

この操作はwebgのページだけでなく、Safariに保存された閲覧履歴とWebサイトデータへ広く影響します。
他のWebサイトのログイン状態などへ影響するため、まず通常の再読み込みやページの開き直しを試し、状態が残る場合にサイトデータの削除を実行してください。
消去後はSafariで対象URLを開き直し、更新後の画面と動作を確認します。


## まとめ

本章では、`webg`を利用するための開発時の基本運用として、リポジトリの相対パスを保ち、ローカルサーバー経由で実行する手順を確認しました。

静的なページは `file://` で閲覧できても、実際の描画処理を含むページはESモジュールや `fetch()`、WebGPUの初期化を必要とするため、実行条件に合うHTTPまたはHTTPSサーバー経由で配信する必要があります。
LAN内のサーバーではセキュアコンテキストを確認し、インターネット上の公開サーバーではHTTPS、MIME type、公開パス、キャッシュを確認します。
この実行環境の基準を明確にしておくことで、今後の学習において「実装の問題」と「実行条件の問題」を混同することなく進めることができます。

続く03章では、物体の位置と回転、親子座標、カメラの距離と画角、表面の法線とUVを説明します。その基準を使い、04章で最初の立方体を表示します。変換の行列やクォータニオンの詳しい計算は41章で確認できます。
