
コードとスクリーンショットで描画の不具合を調べる方法
物体の位置がおかしいのにシェーダーはコンパイルできる。画像には症状があり、コードには複数の原因候補があります。カメラ、行列値、期待結果なしに修正を頼むと、もっともらしい推測になりがちです。
描画不具合の証拠をまとめる
レンダラー/API、関連シェーダー、uniform値、形状、viewport、カメラ、期待画像、実画像、再現操作を集めます。エラーやコンパイル・リンク診断は「正常」だけでなく観測を残します。
| 証拠 | 内容 | 画像だけでは証明できない点 |
|---|---|---|
| 期待と実際の画像 | 同じカメラと解像度、対象領域 | 原因の変換や状態 |
| シェーダーとuniform | 正確な版、行列規則、値 | ホストが何を転送したか |
| 描画設定 | 形状、属性、深度/カリング/混合 | 実際に描いた対象 |
| 再現 | 最小場面と手順 | 別場面でも補修が有効か |
小さな画像では欠落テクスチャと照明異常が似て見えます。可能なら鮮明な拡大を添え、比較中にカメラを変えません。
変換順序を数値で確認する
projection * view * model * positionで、右端から作用します。問題の候補コードです。
gl_Position = uProjection * uModel * uView * vec4(position, 1.0);(1,0,0,1)の期待するクリップ座標は(0,0.6,0,1)です。Model: (1,0) -> (3,0)
View: (3,0) -> (0,3)
Projection: (0,3) -> (0,0.6)
Wrong order: View (1,0)->(0,1), Model ->(2,1), Projection ->(0.4,0.2)仮説・再現・最小パッチを求める
提供された描画差を調査してください。
シェーダー、ホスト状態、期待動作、実画像、版を使用します。
画像は症状であり、特定根因の証明とは扱いません。
出力:観察と根拠、区別する実験付き仮説順位、
首位仮説の最小検証、検証が支持した場合のみパッチ、
判断に足りないuniform・状態・文脈。
指定の行列/ベクトル規則を守ります。
レンダラー全体を書き換えず、カメラ変更で症状を隠しません。
提案だけのテストを実行済みとしません。
入力:証拠と必要な変換規則。本例の補修候補です。
gl_Position = uProjection * uView * uModel * vec4(position, 1.0);最初は行列規約と誤ったシェーダーを渡し、一つの仮説と最小修正を求めます。数値例で(0,0.6)と(0.4,0.2)を区別してから実際の描画を確認します。
画像を判断する前に最小計算を実行する
次のJavaScriptは同じ変換の二次元部分を表します。
const model = ([x, y]) => [x + 2, y];
const view = ([x, y]) => [-y, x];
const projection = ([x, y]) => [x * 0.2, y * 0.2];
const correct = projection(view(model([1, 0])));
const wrong = projection(model(view([1, 0])));
if (Math.abs(correct[0]) > 1e-9 || Math.abs(correct[1] - 0.6) > 1e-9) {
throw new Error("Unexpected reference transform");
}
if (Math.abs(wrong[0] - correct[0]) < 1e-9 &&
Math.abs(wrong[1] - correct[1]) < 1e-9) {
throw new Error("Fixture does not distinguish transform order");
}同じ画像に見える別の原因を区別する
| 現象 | 区別する確認 |
|---|---|
| カメラ移動で位置がおかしい | 既知点の変換と転送値 |
| 一方から物体が消える | 頂点の巻き順、カリング、視線 |
| 位置は正しく遮蔽が違う | 深度添付、クリア、比較状態 |
| テクスチャが伸びる・反転 | UV、画像方向、サンプラーデータ |
| 高密度画面だけ異常 | 描画バッファ、viewport、CSS寸法 |
一条件ずつ変えます。カリングを無効にして見えても、それが正しい最終修正とは限りません。実験と解釈を分けて保存します。
修正と一緒に回帰場面を残す
平行移動と回転が交換できない例を残します。単位行列だけでは本例の誤りを隠します。最小例の後に通常のカメラ運動や代表形状を加え、同じ場面版で比較します。残る別の異常は別件にします。
よくある質問
画像で根因まで分かりますか?
通常は症状と場所が分かります。原因の区別にはコード、状態、再現が必要です。
コンパイル成功なら数学も正しいですか?
合法な式でも変換順序は間違えられます。
提案パッチを一度に試しますか?
一つずつ試し、結果の原因を解釈できるようにします。
JavaScriptでGPUも確認できますか?
指定の計算だけです。描画とホスト状態は別の確認です。
リポジトリ全体を渡しますか?
再現に必要な場面と状態から始め、仮説が要求する依存を追加します。
最終記録には何を残しますか?
版、入力、期待と観測、実験、採用補修、回帰確認、残る不確実性です。
参考資料
- Khronos頂点変換:座標段階。
- MDN行列uniform:WebGL転送。


