OpenGLのマニュアルをローカルに持つ方法
ずっと作り続けているOCamlのSDLバインディングですが、やっとこさ使えるようになってきたので、サンプルとしてOpenGLを同時に使ったものを用意しようとしています。関係無いですが、SDL_Eventの効率的な処理の仕方がわかりません・・・。
話がえらい勢いで飛びましたが、とにかくOpenGLについて何かしらやらないとあきません。が、私はDirectX8〜9くらいしかまともに触ったことがなく、OpenGLがどんなものかは知っていても、実際にはどんな風に使われるのかはさっぱりわかりません。
で、改めて調べてみると、DirectXがとてもありがたく思えるほど混沌としている、ということがなんとなくわかりました・・・。OpenGLってただの規格で、それにどれだけ従うかはベンダー次第ってあーた・・・。
現状、OpenGL2.0くらいが一番普及している＝使えるバージョンで、ここ2,3年くらいのビデオカードなら3.1とかの系列が使えると仮定できて、OpenGL4は出たばっかりなので、最新のカードじゃないと使えない、と。なんとなくそんな理解になっています。合っているかは置いといて。
調べている内に、こんなページがありました。OpenGL3.0以前のOpenGLを「Legacy」であるとして、OpenGL3.0以降への移行を呼び掛けているやつっぽいです。
http://www.opengl.org/wiki/Legacy_OpenGL
OpenGL2.0と3.1以降の大きな違いは(Vertex Object Bufferとかは置いておいて)、前方互換性をついに捨てることが明言されたことと、OpenGL3.1以降では、プログラマブルシェーダーを利用することが基本路線になっていることだと思っています。というか、ぱっと見の人間では、OpenGLの行列設定がわけわからなさすぎていい感じです。まだプログラマブルシェーダーでやる方がわかりやすいような気さえしてくるとは・・・。
愚痴を言っていてもしょうがないので、まずマニュアルを見ることにします。
OpenGL2.1のリファレンス
OpenGL3.3のリファレンス
OpenGL4のリファレンス
それぞれのバージョンごとにあります・・・が、OpenGLのバインディングを作っている段階でわかってましたが、2.1の潜在的な関数の数は半端ありませんねぇ。一番まずいのは使い方がよくわからんことなんですが、こればっかりは本を買うしかないんでしょうかねぇ。赤本？とかいうのが無料で読めるようになっていると聞いたことがありますが。
また話が逸れました。さて、このマニュアルですが、見ていただければわかるように、フレームで分割されています。この形式は結構やっかいで、私がよく使っているFirefoxのScrapBook拡張もまともに動いてくれません。
別にローカルで見なくても、オンラインから見りゃいいじゃん、と言われれば確かにそうなのですが、Macbookを持ち運んだりしていると、通信環境が無いところで開発をやりたくなることはよくあることです。PocketWifiとか持つだけの経済力なんてありません。いつでも見られるというのは大事だと思います。
ちょうどいいことに、さきほどのリファレンスページに、「Downloading Man Page Sources」というセクションがあって、どうもこいつらをダウンロードできるっぽいことが書いてあります。細かいことは以下のリンク先に書いてあります。
http://www.opengl.org/wiki/Getting_started/XML_Toolchain_and_Man_Pages
さて、んじゃあこれに従ってやればいいんじゃん？と思って始めましたが、このページで紹介している方法は、基本的にUbuntu8.04を想定しているようで、私のようなGentoo民は自力でなんとかしないとなりません。調べたところ、他にこの方法を試している人もいないようなので、(他にやりたい人がいるかどうかは置いておいて)実際にやってみた記録を残します。
手順
基本的にはさっきのページに載っていることをやっていくだけですが、私のように英語が苦手な人のために、簡単ですが手順を書いていきます。
まず、それぞれのマニュアルを入れるディレクトリを作り、SVNから最新のマニュアルを取ってきます。
mkdir -p ~/work/opengl/ svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/ man4 svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man3/ man3 svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man2/ man2 svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/manglsl/ manglsl
実は最初のひっかけがここにあって、man2,つまりOpenGL2.0系列のマニュアルが、ページに載ってる通りに入力すると「Not found」と言われてしまいます。正しいのは↑でman2となっています。
これでそれぞれのマニュアルのベースとなるDocBook XMLがダウンロードできました。ところでDocBook XMLってなんなのかというと、Wikipediaによると、
DocBookは技術文書のためのマークアップ言語である。元々の用途はコンピュータのハードウェアやソフトウェアに関する技術文書の作成だったが、他の種類の文書のためにも使うことができる。
DocBookの利点のうち特に大きなものの一つは、文書内容の論理的な構造を表す、表示形式に依存しない文書の作成が可能となることである。そのようにして作った文書はユーザーが文書に手を入れることなく、HTML・PDF・manページ・HTMLヘルプなどの様々なフォーマットで出力できる。
https://ja.wikipedia.org/wiki/DocBook
ということらしいです。恥ずかしながら初めて知りました。
さて、次は生成に必要な各種ツールをインストールします。まず、docbookで利用するcatalogというのを設定するために、↓のパッケージをemergeします。
sudo emerge build-docbook-catalog docbook-xls-stylesheets
多分この二つだけで大丈夫・・・だと思います。
次に、mathml 2.0 DTDの設定を行ないます。
sudo xmlcatalog --noout --add public "-//W3C//DTD MathML 2.0//EN" "file:///usr/share/xml/schema/w3c/mathml/dtd/mathml2.dtd" /etc/xml/catalog sudo xmlcatalog --noout --add public "-//W3C//DTD MathML//EN" "file:///usr/share/xml/schema/w3c/mathml/dtd/mathml2.dtd" /etc/xml/catalog sudo xmlcatalog --noout --add system "http://www.w3.org/TR/MathML2/dtd/mathml2.dtd" "file:///usr/share/xml/schema/w3c/mathml/dtd/mathml2.dtd" /etc/xml/catalog sudo xmlcatalog --noout --add public "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "file:///usr/share/xml/schema/w3c/mathml/dtd/xhtml-math11-f.dtd" /etc/xml/catalog sudo xmlcatalog --noout --add system "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd" "file:///usr/share/xml/schema/w3c/mathml/dtd/xhtml-math11-f.dtd" /etc/xml/catalog
・・・さて、ここで私は「あれ？」となりました。だってここでfile://以下に指定しているファイルが無いんですから・・・。
解説ページには、MathML 1.1 については手動で入れるように書いていますが、GentooではMathML 2.0 についても手動で入れないとならないっぽいです。(私が知らないだけかもしれませんので、ご存知の方は教えてください)
cd ~/work/opengl wget http://www.docbook.org/xml/mathml/1.1CR1/dbmathml.dtd wget http://www.w3.org/Math/DTD/mathml2.tgz tar xf mathml2.tgz sudo cp -r mathml2 /usr/share/xml/ sudo mkdir -p /usr/share/xml/docbook-mathml-dtd-1.1CR1 sudo cp -f dbmathml.dtd /usr/share/xml/docbook-mathml-dtd-1.1CR1 sudo xmlcatalog --noout --add public "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" "file:///usr/share/xml/docbook-mathml-dtd-1.1CR1/dbmathml.dtd" /etc/xml/catalog sudo xmlcatalog --noout --add system "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd" "file:///usr/share/xml/docbook-mathml-dtd-1.1CR1/dbmathml.dtd" /etc/xml/catalog xmlcatalog --noout --add public "-//W3C//DTD MathML 2.0//EN" \ "file:///usr/share/xml/mathml2/mathml2.dtd" \ /etc/xml/catalog xmlcatalog --noout --add system \ "http://www.w3.org/TR/MathML2/dtd/mathml2.dtd" \ "file:///usr/share/xml/mathml2/mathml2.dtd" \ /etc/xml/catalog
なお、MathML 2.0の導入のしかたは、解説ページのCygwinセクションに載っています。
これでなんとなく準備が整いました。試しにOpenGL 2.0のxhtml+mathmlを生成してみましょう。
cd man2 make ROOT=`pwd`
なんか色々と警告が出ますけども進めます。ただ、途中でとある.xmlが無いために、makeが止まってしまう場所があります。これについては、makeをしたディレクトリにxhtmlというディレクトリがありますので、その中のMakefileから、エラーが発生したファイルを削除してから再度makeすればOKです。
すると、xhtml/index.htmlというファイルができるので、こいつを開けば、とりあえず使えます。いや、使うだけならばindex.phpを開いてやればいいのですが・・・。index.phpをブラウザで開くと、当然ながらphpを使ってないので、なんか色々と足りない状態になりますが、実用には問題なかったりします。
しかし今回はmanで開くのが目的なので、実はこの手順はなくってもいいんです。解説ページでは「Output manual pages to man format」に書いてあります。
cd ~/work/opengl wget http://sourceforge.net/projects/docbook/files/docbook-xsl/1.76.1/docbook-xsl-1.76.1.tar.bz2 tar xf docbook-xls-1.76.1.tar.bz2 cd man2 for i in `ls *xml`; do xsltproc --noout --nonet ../docbook-xls-1.76.1/manpages/docbook.xsl $i; done for i in `ls *.3G`; do mv $i `basename $i .3G`.1; done
xsltprocで変換すると、どういう拡張子なのかはよくわかりませんが、.3Gというファイルができあがります。これを.3Gから.1へ拡張子を変換してやります。これで準備はできました。後は、MANPATHにこのディレクトリを追加してやればよいです。
export MANPATH=`pwd`:$MANPATH man glGet
で、glGetについてmanで見られるはずです。個人的には、数式とかも見られるので、ブラウザで見た方がいいとは思いますが・・・。MacOSXではデフォルトでOpenGLのmanが見られるようになっているそうですので、需要はあるんでしょう。
同様にOpenGL3.*、4.*も変換すれば、セクションを指定することでそれぞれのバージョンのmanが見られる、という感じにもできると思います。私は当面2.1があればいいので・・・。
今回はまたニッチな需要と思われる、OpenGLのドキュメントをローカルで閲覧するための方法を書いてみました。ほとんど需要は無いかと思いますが、英語ページにしか情報が無いのもなんなんで。
