syghの新フラグメント置き場

プログラミングTipsやコード断片の保管場所です。お絵描きもときどき載せます。

MSDN DirectX SDKヘルプの記載ミス

(これは2011-02-12に書いた、故OCNブログの記事を移植したものです)

D3DX10 のヘッダーを調べればすぐに分かることなんですが、下記の ID3DX10Mesh::Optimize() メソッドに関して、2011-02-12 現在、MSDN のヘルプが間違っているので備忘録として残しておきます。チェック対象は DirectX SDK June 2010。
http://msdn.microsoft.com/ja-jp/library/ee420093.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/bb173925.aspx

HRESULT ID3DX10Mesh::Optimize(
UINT Flags,
UINT *pFaceRemap,
LPD3D10BLOB *ppVertexRemap
);
  • 最適化フラグを表す Flags パラメータに渡せるのは、D3DXMESHOPT ではなく _D3DX10_MESHOPT の誤り。
  • D3DXMESHOPT シンボルは存在せず、_D3DXMESHOPT 列挙体は存在するが D3DX9 用。
  • D3DXMESH シンボルは存在せず、_D3DXMESH 列挙体は存在するが D3DX9 用。
  • さらに、D3DX10 用の _D3DX10_MESH 列挙体のメンバーは、D3DX9 用の _D3DXMESH 列挙体のメンバーと比べて随分減っており、メンバーのうち、D3DX10_MESH_32_BIT だけでなく D3DX10_MESH_GS_ADJACENCY も最適化フラグとして使えないはず(ちなみに D3DX10_MESH シンボルはない)。

ちなみに、
Direct3D 9 の D3DX9 には ID3DXMesh と ID3DXSkinInfo が、
Direct3D 10 の D3DX10 には ID3DX10Mesh と ID3DX10SkinInfo があり、
それぞれ Direct3D プログラミングの入門者には非常に便利なインターフェイスだったんですが、
Direct3D 11 の D3DX11 には ID3DX11Mesh も ID3DX11SkinInfo も存在しません。

それはそうとアンダースコアをシンボル名の最初に使うのは MS 謹製ライブラリといえどやめて欲しいです。

あと

typedef enum _D3DX10_MESH_DISCARD_FLAGS
{
...
} D3DX10_MESH_DISCARD_FLAGS;

とかいうのも NG です。アンダースコア付きのシンボルを定義する必要はまったくなく、両方 D3DX10_MESH_DISCARD_FLAGS にしておけば良いです。アンダースコアで始まるシンボル名は処理系(コンパイラ)用のために予約されてるものがあるからユーザーコードで使うべきでないっていうのはマイクロソフト謹製の DirectX SDK にだって該当する話です。また、使いもしない typedef シノニムがあると、インテリセンスのデータベースに余計なシンボル情報が登録されてしまうのでやめて欲しい……

ちなみに Win32 API には

typedef struct tagBITMAP
{
...
} BITMAP;

とかいう定義が大量にありますが、これもマネしないようにしましょう。

その他

他にも DirectX SDK のヘルプにはミスが多数あるのですが、とりあえず気付いたものを列挙しておきます。日本語版のみに存在するミスが多いです。あと日本語版はなぜかページ内サンプルコードの改行が全部なくなってしまっているので読みづらくてしかたないです。結局英語版も読む羽目になります。

・HLSL
https://msdn.microsoft.com/ja-jp/library/bb509561.aspx
https://msdn.microsoft.com/ja-jp/library/ee418149.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/bb509561.aspx

HLSLが導入されたのはDirectX 9です。DirectX 8ではありません。


・reflect (DirectX HLSL)
http://msdn.microsoft.com/ja-jp/library/bb509639.aspx
http://msdn.microsoft.com/ja-jp/library/ee418347.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/bb509639.aspx

MSDN 英語版では内積 dot(i, n) のドット記号に UCS-2 2022H が使われているが、日本語版では翻訳する際のミスで化けて「?」になってしまっている模様。いわゆる Shift_JIS 病の発動。


スカラー型 (DirectX HLSL)
http://msdn.microsoft.com/ja-jp/library/ee418354.aspx
http://msdn.microsoft.com/en-us/library/bb509646.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/bb509646.aspx

uniform を「均一」と訳すべきではない。もともと原文が指している「uniform global variable」は定数レジスタ・定数バッファのことなので、もしどうしても日本語に直したいのであれば「不変」とするべき。


・D3DXVec3TransformCoord
http://msdn.microsoft.com/ja-jp/library/bb205522.aspx
http://msdn.microsoft.com/ja-jp/library/ee417622.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/bb205522.aspx

「ベクトル pV (x, y, 0, 1) を行列 pM によって……」ではなく「ベクトル pV (x, y, z, 1) を行列 pM によって……」のはず。英語版ではちゃんと (x, y, z, 1) になっている。


・ID3D10Device/ID3D11DeviceContext::UpdateSubresource
https://msdn.microsoft.com/ja-jp/library/bb173621.aspx
https://msdn.microsoft.com/ja-jp/library/ee419755.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/ff476486.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/bb173621.aspx

メソッドのコピー先にできないリソースの条件が Remarks に記述されているが、「the resource is created with immutable or dynamic usage.」の部分に相当する翻訳「リソースが固定で作成されている場合。」が大嘘。それと、ヘタに「固定」とかいうふうに無理やり日本語化しないで、immutable のままにしておくべき(まともな C++ プログラマーだったら mutable/immutable くらい誰でも知っている)。


・D3D10_USAGE_DYNAMIC/D3D11_USAGE_DYNAMIC
https://msdn.microsoft.com/ja-jp/library/bb172499.aspx
https://msdn.microsoft.com/ja-jp/library/ee416352.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/bb172499.aspx
https://msdn.microsoft.com/en-us/library/windows/desktop/ff476259.aspx

「To write to a dynamic resource on the CPU, use a Map method. You can write to a dynamic resource on the GPU using CopyResource or CopySubresourceRegion.」および「To update a dynamic resource, use a Map method.」の部分に相当する翻訳「動的リソースを更新する方法は 2 つあります。データの配置がリソース内での格納方法と同じである場合は ID3D10Device::UpdateSubresource を使用します。それ以外の場合は Map メソッドを使用します。」および「動的リソースを更新する方法は 2 つあります。データの配置がリソース内での格納方法と同じである場合は ID3D11DeviceContext::UpdateSubresource を使用します。それ以外の場合は Map メソッドを使用します。」が大嘘。いったい何をどうしたらこんな誤訳が出てくるのか、まったくもって意味不明。


・numthreads
http://msdn.microsoft.com/ja-jp/library/ee422317.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/ff471442.aspx

cs_4_x における最大ローカルグループスレッド数は「786」ではなく「768」。英語の原文では正しいが、日本語に翻訳する際になぜか記載ミスしている。ちなみに 768=256*3 なので普通に間違えていることくらい気づきそうなものだが、この間違った記述をなんの疑いもなくそのまま誤って転載しているとおぼしき個人サイトをいくつか発見した。


・SV_GroupIndex
http://msdn.microsoft.com/ja-jp/library/ee422450.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/ff471569.aspx

MSDN 英語版では「(numthreadsX × numthreadsY × numThreadsZ) - 1」のハイフン記号に UCS-2 2013H が使われているが、日本語版では翻訳する際のミスで化けて「?」になってしまっている模様。またもや Shift_JIS 病の発動。


・OutputPatch
http://msdn.microsoft.com/ja-jp/library/ee422340.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/ff471464.aspx

Length プロパティが「長さ」と日本語訳されてしまっている。余計なお世話。ちなみにこういうのは機械翻訳でよくあることなのだが、おそらく機械翻訳をベースにして、技術的な知識のない人間が部分的に手を入れているのでこういうミスが出るものと思われる。


・シェーダー モデル 5 のオブジェクト
http://msdn.microsoft.com/ja-jp/library/ee416226.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/ff471359.aspx

Buffer オブジェクトだけ「バッファー」と日本語訳されてしまっている。機械翻訳の名残。


・ShadowVolume10 サンプル
http://msdn.microsoft.com/ja-jp/library/ee416427.aspx

CDXUTMesh10::ConvertToAdjacencyIndices は CDXUTSDKMesh::CreateAdjacencyIndices の誤り。
DirectX 10 時代の DXUT では存在したのかもしれないが、少なくとも June 2010 には存在しない。
ちなみにこのメソッドの中では ID3DX10Mesh::GenerateGSAdjacency() が使われているが、DirectX 11 用の D3DX には ID3DX11Mesh がないので、DirectX 11 に移植する場合はこの隣接性情報(隣接インデックス バッファ)生成処理(ブラックボックス)に相当するものを自前で用意する必要がある。なお、DXUT11 の CDXUTSDKMesh::CreateFromMemory() を見る限り、DXUT11 では隣接性情報を生成してない模様(手抜きというか未実装)。


・カスケード シャドウ マップ
http://msdn.microsoft.com/ja-jp/library/ee416307.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/ee416307.aspx

DirectX SDK 付属のサンプル、CascadedShadowMaps11 と VarianceShadows11 の両方にまたがる詳細な解説が載っており、この記事自体は非常に有用であるものの、日本語版では翻訳ミス("derivative"を「派生」と訳しているが、「偏微分」もしくは「差分」と訳すべき)があったり、原文にはあるはずの図(Figure 4)が欠けていたりする。


上記のミスはすべてフィードバックしたんですが、MS Japan は全般的に非常に怠惰な人間が多いらしく、2014年4月現在、いまだにひとつも修正されていません。DirectX 11.1, 11.2 のヘルプもいまだに日本語へ翻訳されていないことを考えると、(Windows SDK 8.x で廃止された D3DX や DXUT はともかく)DirectX 11.0 コアライブラリやシェーダーモデル5.0のヘルプの間違いくらいはさっさと修正して欲しいです。Xbox One の日本展開のことや、DirectX 12 のことまで考えると先が思いやられます。
MS Japan は本当に日本の(特にインディーズ)開発者に情報提供する気があるんでしょうか?
あと技術的な知識のない人間に翻訳作業をさせるのはもう本当にやめて欲しいです。完全に余計なお世話です。そんな害悪しかもたらさないものを、恥も外聞もなく堂々と全世界に向けて発信するくらいだったら、最初から正確な英語版のドキュメントだけ公開してください。