JSR-184 相機封裝實戰：LookAt 矩陣算法與跨平台適配方案

背景：JSR-184 與 Mascot Capsule 相機模型差異

JSR-184 (Mobile 3D Graphics API) 採用矩陣堆疊與 Transform 物件控制相機，而 Mascot Capsule v3 沿用傳統 lookAt(position, direction, upVector) 介面。為實現跨引擎相容，Digital Chocolate 封裝了統一的 setLookAt() 方法，同時支援兩種渲染後端。

LookAt 矩陣數學原理

給定：

• 相機位置 E (eye position)
• 觀察目標 T (look-at target) → 方向向量 L = normalize(T - E)
• 上方向 U (up vector，需正交化)

構建右手座標系基向量：

1. Side (Right) 向量：S = L × U (叉積) → 正規化
2. 修正 Up 向量：U' = S × L (保證正交單位)
3. 視圖矩陣 (Column-major，OpenGL 風格)：

[ Sx   Uy  -Lx   Ex ]
[ Sy   Uy  -Ly   Ey ]
[ Sz   Uz  -Lz   Ez ]
[ 0    0    0    1  ]

JSR-184 實現代碼 (M3G 後端)

public static final void setLookAt(float posX, float posY, float posZ,
                                   float lookX, float lookY, float lookZ,
                                   float upX, float upY, float upZ) {
    // 假設 USE_M3G 常數控制後端切換
    if (USE_M3G) {
        // 1. 計算 Side 向量 (叉積)
        float sideX = lookY * upZ - lookZ * upY;
        float sideY = lookZ * upX - lookX * upZ;
        float sideZ = lookX * upY - lookY * upX;
        
        // 2. 正規化 Side
        float invLen = 1.0f / (float) Math.sqrt(sideX*sideX + sideY*sideY + sideZ*sideZ);
        sideX *= invLen; sideY *= invLen; sideZ *= invLen;
        
        // 3. 重新計算正交 Up 向量
        upX = sideY * lookZ - sideZ * lookY;
        upY = sideZ * lookX - sideX * lookZ;
        upZ = sideX * lookY - sideY * lookX;
        // 此時 up 已為單位向量，因 side ⟂ look
        
        // 4. 填充 4x4 矩陣 (column-major 順序)
        sm_mtx[0]  = sideX;  sm_mtx[1]  = upX;    sm_mtx[2]  = -lookX; sm_mtx[3]  = posX;
        sm_mtx[4]  = sideY;  sm_mtx[5]  = upY;    sm_mtx[6]  = -lookY; sm_mtx[7]  = posY;
        sm_mtx[8]  = sideZ;  sm_mtx[9]  = upZ;    sm_mtx[10] = -lookZ; sm_mtx[11] = posZ;
        sm_mtx[12] = 0.0f;   sm_mtx[13] = 0.0f;   sm_mtx[14] = 0.0f;   sm_mtx[15] = 1.0f;
        
        // 5. 套用至 M3G Transform 物件
        sm_m3gTransform.set(sm_mtx);
    }
    
    // Mascot Capsule v3 後端 (整數定點數運算)
    if (USE_MASCOT) {
        sm_mascotTmpVectorA.set((int)posX, (int)posY, (int)posZ);
        sm_mascotTmpVectorB.set((int)(lookX * MASCOT_ONE), 
                                (int)(lookY * MASCOT_ONE), 
                                (int)(lookZ * MASCOT_ONE));
        sm_mascotTmpVectorC.set(0, MASCOT_ONE, 0); // 世界上方向
        sm_mascotAffineTrans.lookAt(sm_mascotTmpVectorA, 
                                    sm_mascotTmpVectorB, 
                                    sm_mascotTmpVectorC);
    }
}

關鍵實現細節與避坑指南

• 輸入前置條件：look 與 up 向量必須預先正規化
• 矩陣佈局：JSR-184 Transform.set(float[]) 採 column-major (OpenGL 風格)，非 row-major
• Z 軸慣例：視圖矩陣中 -look 代表相機朝向 -Z 軸 (右手系)
• 數值穩定性：叉積長度接近零時 (look ∥ up) 會導致除零，實際應用需加保護判斷
• 固定點數轉換：Mascot 使用 16.16 定點數 (MASCOT_ONE = 65536)，浮點乘轉換時注意精度

工程應用建議

1. 將此封裝置於共用數學工具類，上層遊戲邏輯統一呼叫 CameraHelper.setLookAt()
2. 編譯期透過宏/常數切換後端，避免運行期分支開銷
3. 單元測試驗證：已知位置/目標/上向量，檢查矩陣轉換後的標準基向量是否符合預期

此方案完美解決了 JSR-184 與傳統 3D 引擎相機控制 API 的互操作難題，是跨平台 3D 遊戲移植的關鍵基建模組。