opengl 0.8.0 → 0.9.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (145) hide show
  1. checksums.yaml +7 -0
  2. checksums.yaml.gz.sig +1 -0
  3. data.tar.gz.sig +0 -0
  4. data/.gitignore +2 -1
  5. data/.travis.yml +19 -0
  6. data/History.rdoc +26 -0
  7. data/Manifest.txt +3 -23
  8. data/README.rdoc +43 -37
  9. data/Rakefile +6 -62
  10. data/examples/NeHe/nehe_lesson02.rb +3 -2
  11. data/examples/NeHe/nehe_lesson03.rb +3 -2
  12. data/examples/NeHe/nehe_lesson04.rb +3 -1
  13. data/examples/NeHe/nehe_lesson05.rb +4 -1
  14. data/examples/NeHe/nehe_lesson06.rb +9 -6
  15. data/examples/NeHe/nehe_lesson07.rb +9 -6
  16. data/examples/NeHe/nehe_lesson08.rb +9 -6
  17. data/examples/NeHe/nehe_lesson09.rb +10 -6
  18. data/examples/NeHe/nehe_lesson11.rb +9 -6
  19. data/examples/NeHe/nehe_lesson12.rb +9 -6
  20. data/examples/NeHe/nehe_lesson16.rb +50 -47
  21. data/examples/NeHe/nehe_lesson19.rb +10 -7
  22. data/examples/NeHe/nehe_lesson36.rb +234 -229
  23. data/examples/OrangeBook/brick.rb +227 -225
  24. data/examples/OrangeBook/particle.rb +233 -231
  25. data/examples/RedBook/aapoly.rb +71 -70
  26. data/examples/RedBook/aargb.rb +54 -52
  27. data/examples/RedBook/accanti.rb +96 -94
  28. data/examples/RedBook/accpersp.rb +106 -104
  29. data/examples/RedBook/alpha.rb +54 -52
  30. data/examples/RedBook/alpha3D.rb +90 -88
  31. data/examples/RedBook/bezcurve.rb +48 -46
  32. data/examples/RedBook/bezmesh.rb +71 -69
  33. data/examples/RedBook/checker.rb +57 -55
  34. data/examples/RedBook/clip.rb +41 -39
  35. data/examples/RedBook/colormat.rb +72 -70
  36. data/examples/RedBook/cube.rb +39 -37
  37. data/examples/RedBook/depthcue.rb +37 -35
  38. data/examples/RedBook/dof.rb +110 -109
  39. data/examples/RedBook/double.rb +40 -38
  40. data/examples/RedBook/drawf.rb +30 -28
  41. data/examples/RedBook/feedback.rb +79 -77
  42. data/examples/RedBook/fog.rb +90 -89
  43. data/examples/RedBook/font.rb +78 -76
  44. data/examples/RedBook/hello.rb +29 -27
  45. data/examples/RedBook/image.rb +57 -55
  46. data/examples/RedBook/jitter.rb +131 -131
  47. data/examples/RedBook/light.rb +2 -1
  48. data/examples/RedBook/lines.rb +70 -68
  49. data/examples/RedBook/list.rb +48 -46
  50. data/examples/RedBook/material.rb +200 -199
  51. data/examples/RedBook/mipmap.rb +84 -82
  52. data/examples/RedBook/model.rb +55 -53
  53. data/examples/RedBook/movelight.rb +52 -50
  54. data/examples/RedBook/pickdepth.rb +103 -101
  55. data/examples/RedBook/planet.rb +46 -44
  56. data/examples/RedBook/quadric.rb +97 -95
  57. data/examples/RedBook/robot.rb +55 -53
  58. data/examples/RedBook/select.rb +118 -116
  59. data/examples/RedBook/smooth.rb +35 -33
  60. data/examples/RedBook/stencil.rb +96 -94
  61. data/examples/RedBook/stroke.rb +75 -73
  62. data/examples/RedBook/surface.rb +93 -91
  63. data/examples/RedBook/teaambient.rb +71 -69
  64. data/examples/RedBook/teapots.rb +105 -103
  65. data/examples/RedBook/tess.rb +96 -94
  66. data/examples/RedBook/texbind.rb +79 -77
  67. data/examples/RedBook/texgen.rb +88 -86
  68. data/examples/RedBook/texturesurf.rb +57 -55
  69. data/examples/RedBook/varray.rb +85 -83
  70. data/examples/RedBook/wrap.rb +76 -74
  71. data/examples/misc/OGLBench.rb +114 -113
  72. data/examples/misc/anisotropic.rb +154 -152
  73. data/examples/misc/fbo_test.rb +37 -36
  74. data/examples/misc/font-glut.rb +47 -46
  75. data/examples/misc/glfwtest.rb +16 -16
  76. data/examples/misc/plane.rb +13 -13
  77. data/examples/misc/readpixel.rb +66 -65
  78. data/examples/misc/sdltest.rb +21 -19
  79. data/examples/misc/trislam.rb +548 -547
  80. data/ext/opengl/common.h +16 -38
  81. data/ext/opengl/conv.h +39 -41
  82. data/ext/opengl/extconf.rb +4 -31
  83. data/ext/opengl/funcdef.h +126 -124
  84. data/ext/opengl/gl-1.0-1.1.c +1917 -1917
  85. data/ext/opengl/gl-1.2.c +4 -667
  86. data/ext/opengl/gl-1.3.c +9 -9
  87. data/ext/opengl/gl-1.4.c +8 -8
  88. data/ext/opengl/gl-1.5.c +1 -1
  89. data/ext/opengl/gl-2.0.c +392 -388
  90. data/ext/opengl/gl-3.0.c +493 -0
  91. data/ext/opengl/gl-enums.c +1523 -5
  92. data/ext/opengl/gl-enums.h +4679 -122
  93. data/ext/opengl/gl-error.c +7 -7
  94. data/ext/opengl/gl-error.h +4 -4
  95. data/ext/opengl/gl-ext-arb.c +468 -464
  96. data/ext/opengl/gl-ext-ext.c +18 -18
  97. data/ext/opengl/gl-ext-nv.c +15 -15
  98. data/ext/opengl/gl.c +2 -0
  99. data/ext/opengl/gl_buffer.c +92 -92
  100. data/ext/opengl/opengl.c +1 -7
  101. data/lib/opengl.rb +23 -59
  102. data/lib/opengl/test_case.rb +1 -2
  103. data/test/dummy.xorg.conf +140 -0
  104. data/test/test_gl.rb +18 -22
  105. data/test/test_gl_10_11.rb +220 -220
  106. data/test/test_gl_12.rb +11 -122
  107. data/test/test_gl_13.rb +202 -210
  108. data/test/test_gl_14.rb +16 -19
  109. data/test/test_gl_15.rb +2 -4
  110. data/test/test_gl_20.rb +45 -58
  111. data/test/test_gl_21.rb +46 -163
  112. data/test/test_gl_ext_arb.rb +54 -72
  113. data/test/test_gl_ext_ati.rb +0 -2
  114. data/test/test_gl_ext_ext.rb +66 -66
  115. data/test/test_gl_ext_gremedy.rb +8 -15
  116. data/test/test_gl_ext_nv.rb +109 -112
  117. data/test/test_opengl_buffer.rb +8 -25
  118. data/utils/README +0 -5
  119. data/utils/enumgen.rb +72 -76
  120. data/utils/extlistgen.rb +55 -55
  121. metadata +87 -66
  122. metadata.gz.sig +2 -0
  123. data/Rakefile.cross +0 -107
  124. data/docs/build_install.txt +0 -119
  125. data/docs/extensions.txt.in +0 -348
  126. data/docs/history.txt +0 -66
  127. data/docs/requirements_and_design.txt +0 -117
  128. data/docs/roadmap.txt +0 -28
  129. data/docs/scientific_use.txt +0 -35
  130. data/docs/supplies/page_template.html +0 -71
  131. data/docs/thanks.txt +0 -29
  132. data/docs/tutorial.txt +0 -469
  133. data/ext/opengl/glu-enums.c +0 -164
  134. data/ext/opengl/glu-enums.h +0 -463
  135. data/ext/opengl/glu.c +0 -1534
  136. data/ext/opengl/glut.c +0 -1145
  137. data/ext/opengl/glut_callbacks.c +0 -845
  138. data/lib/glu.rb +0 -1
  139. data/lib/glut.rb +0 -1
  140. data/test/test_glu.rb +0 -309
  141. data/utils/mkdn2html.rb +0 -59
  142. data/utils/post-mkdn2html.rb +0 -91
  143. data/website/images/ogl.jpg +0 -0
  144. data/website/images/tab_bottom.gif +0 -0
  145. data/website/style.css +0 -198
@@ -1,66 +0,0 @@
1
- Project history
2
- ===============
3
-
4
- The [original ruby-opengl](http://www2.giganet.net/~yoshi/) was written
5
- by Yoshi.
6
-
7
- James A. desperately wanted to get the OpenGL Ruby bindings working on his Mac,
8
- but they wouldn't even compile on OSX. After a little bit of tweaking, he made
9
- his patched bindings available to the ruby community in a very informal manner.
10
-
11
- John G. then wanted to clean it up and add some docs to it, and so started
12
- tweaking and put up a new site and made his changes available.
13
-
14
- Then Peter M. came along and decided to try updating ruby-opengl using SWIG,
15
- as it seemed easier than doing everything by hand. Peter wrote the new code,
16
- John started the actual RubyForge project, put up a new site, and Peter
17
- committed the code.
18
-
19
- Thu M. V. joined the project with a lot of energy, and the mailing list
20
- was showing a good bit of activity.
21
-
22
- After some experience, we began to question whether SWIG was necessary/helpful
23
- for a project of this nature. The leaning was that people want to abandon
24
- SWIG and go back to maintaining the binding files by hand. Thu even provided
25
- a script to help with the manual coding that would be required without using
26
- SWIG.
27
-
28
- The reasoning at the time was:
29
-
30
- Pro-SWIG:
31
-
32
- * Could use the .i files for another project, perhaps (OTOH, we couldn't
33
- use previous .i files on this project...)
34
-
35
- * It's supposed to require less manual coding.
36
-
37
- Con-SWIG:
38
-
39
- * yet another tool to learn
40
-
41
- * OpenGL isn't really all that big
42
-
43
- * OpenGL doesn't change a lot
44
-
45
- * A lot of boilerplate and overhead in the generated files because SWIG is
46
- a general tool.
47
-
48
-
49
- In September 2006, we stopped using SWIG. Thu and Peter began fine tuning
50
- Thu's original `utils/mkwrap.rb` script.
51
-
52
- Development stalled in October 2006.
53
-
54
- Development picked up again towards the end of 2006. After a long hiatus
55
- and getting a new release of mkrf out the door, version 0.33 (following the
56
- numbering of original Yoshi's bindings which stalled at 0.32) was released.
57
-
58
- During first half of 2007, we added large portion of code, as well as number
59
- of unit tests, creating near-complete support for OpenGL 2.1.
60
- Support for MS Windows was also added during this time.
61
-
62
- Version 0.40 was released in July 2007.
63
-
64
- Version 0.50 was released in October 2007.
65
-
66
- Version 0.60 was released in December 2007.
@@ -1,117 +0,0 @@
1
- Design
2
- ======
3
-
4
- This document records the requirements, high-level design, and the
5
- specifications for the ruby-opengl project.
6
-
7
- The content of this document was gleaned from the postings on the
8
- ruby-opengl-dev list and internal notes from John G., Peter M., Vo Minh Thu,
9
- and Robert K.
10
-
11
-
12
- Requirements
13
- ------------
14
-
15
- * ruby-opengl is a Ruby extension library which wraps the OpenGL, GLU,
16
- and GLUT libraries.
17
-
18
- * ruby-opengl shall provide three base modules: *BaseGL*, *BaseGLU*, and
19
- *BaseGLUT* (the "Base Modules").
20
-
21
- Note: "BaseGL" etc. are not the names that appear in the code -- they are
22
- just handles so we can write about them in documents like this one.
23
-
24
- * The Base Modules shall be separately loadable.
25
-
26
- * BaseGL shall not depend on any of the other Ruby modules.
27
-
28
- * BaseGLU shall depend on, at most, BaseGL.
29
-
30
- * BaseGLUT shall depend on, at most, BaseGLU and BaseGL.
31
-
32
- * Base Module syntax shall closely follow the standard C-syntax.
33
-
34
- The syntax for a Ruby program that uses the base modules, shall closely
35
- follow the standard C-like syntax that OpenGL programmers are used to,
36
- and that most OpenGL examples are published in:
37
-
38
- {{ruby}}
39
- require 'gl'
40
- Gl.glBegin( Gl::GL_POLYGON )
41
- Gl.glVertex2d( 0, 0 )
42
- Gl.glVertex2d( 0, 1 )
43
- Gl.glVertex2d( 1, 1 )
44
- Gl.glVertex2d( 1, 0 )
45
- Gl.glEnd
46
-
47
- Or:
48
-
49
- {{ruby}}
50
- require 'gl'
51
- include Gl
52
- glBegin( GL_POLYGON )
53
- glVertex2d( 0, 0 )
54
- glVertex2d( 0, 1 )
55
- glVertex2d( 1, 1 )
56
- glVertex2d( 1, 0 )
57
- glEnd
58
-
59
- The rationale for adopting the C-like syntax is:
60
- * Makes it familiar to OpenGL programmers.
61
- * Removes the burden of learning OpenGL plus some Ruby-isms, just to
62
- get started.
63
- * Makes it easier to port OpenGL programs to/from ruby-opengl.
64
- * The current OpenGL documentation more naturally fits ruby-opengl.
65
- * Putting "gl", "glu" and "glut" in front of all the names (i.e.,
66
- following the C-like syntax) leaves common variable names open for
67
- the programmers (e.g., "vertex", "color" etc. are popular topics in
68
- 3D programming, so not robbing the ruby namespace of such valuable
69
- real-estate seems nice).
70
-
71
-
72
- * It shall be possible to check out the project from svn, compile and test
73
- on the following platforms: Mac OS X, GNU/Linux. MS Windows operating
74
- systems may also be supported in the future.
75
-
76
- * The project will make a number of pre-compiled extensions available as gems.
77
-
78
- * The project will supply source code and build scripts (via svn checkout)
79
- conducive to straightforward porting to other platforms.
80
-
81
- * There shall be a test suite that exercises each call in each of the Base
82
- modules.
83
-
84
- * All project documentation will be in Markdown format in files that end in
85
- `.txt`.
86
-
87
- * The project will make some efforts to track versions of OpenGL.
88
-
89
-
90
- ### Things in the future
91
-
92
- Once the base modules are implemented, there are several ideas on things to
93
- do next. This list is not really requirements, but a list of nice ideas to
94
- try:
95
-
96
- * Provide wrappers for glBegin/glEnd, eg: polygon()...translates to
97
- glBegin(GL_POLYGON)....glEnd
98
-
99
- * Untyped versions of the multi-typed gl functions: e.g., a single
100
- glVertex that examines its arguments and calls the appropriate
101
- glVertex{234}{fisdv} call in BaseGL.
102
-
103
-
104
-
105
- Implementation
106
- --------------
107
-
108
- Our plan is to continue on with Yoshi's original code, modified
109
- to use standard OpenGL-style constant and function names.
110
-
111
-
112
- ### Build environment ###
113
-
114
- The build environment will use:
115
-
116
- * use rake and mkrf.
117
- * minimize the number of additional tools required
@@ -1,28 +0,0 @@
1
- Roadmap
2
- =======
3
-
4
- * Write comprehensive API documentation
5
- * Create more example code
6
- * Add RMagick(ImageMagick) integration for easy image handling (textures,screenshots)
7
- * Support all pixelstore modes (currently forced to default values by
8
- any function getting/setting data affected by it)
9
-
10
- Possible Features
11
- ========
12
- * Add **all** OpenGL extensions (some are obsolete or not really used or useful at all)
13
- * Add direct mapping on ruby types for vertex arrays, buffers and image data to allow high performance data operations from within ruby
14
- - this should be modeled after Perl's OpenGL::Array
15
- - Update: preliminary tests shows that performance-wise there is no need for it, as the Ruby interpreter overhead is currently larger than immediate-mode calls overhead, so any potential speed gains are in domain of 1-5%. It still may be good idea from usability perspective, although that would require more comprehensive design, not just simple wrapper.
16
- * Support for r/w VBO buffer mapping - gl(Un)MapBuffer (is it needed?)
17
-
18
- <br/>
19
- <br/>
20
- <br/>
21
- <br/>
22
- <br/>
23
- <br/>
24
- <br/>
25
- <br/>
26
- <br/>
27
- <br/>
28
- <br/>
@@ -1,35 +0,0 @@
1
- Scientific Use
2
- --------------
3
-
4
- Though not directly related to ruby-opengl, this page contains a
5
- few tidbits of general info that might possibly be of interest to
6
- a number of users.
7
-
8
- There are currently two bindings to the [GNU Scientific Library][1] (GSL):
9
-
10
- * Yoshiki's Ruby/GSL (<http://rb-gsl.rubyforge.org/>) --
11
- Comes with an API reference. Also, I've been told that the API has been
12
- worked a bit to be more comfortable for Ruby programmers.
13
- * Arno's ruby-gsl (<http://ruby-gsl.sourceforge.net/>) --
14
- more of a straight wrapper around the C API.
15
-
16
- [1]: http://www.gnu.org/software/gsl/
17
-
18
- <a href="http://rubyforge.org/softwaremap/trove_list.php?form_cat=97">Browse Rubyforge</a>
19
- for more.
20
-
21
-
22
- Links
23
- -----
24
-
25
- * <http://sciruby.codeforpeople.com/sr.cgi/FrontPage> -- SciRuby wiki.
26
- * <http://narray.rubyforge.org/> -- Numerical n-dimensional Array class.
27
- * <http://www.kitp.ucsb.edu/~paxton/tioga.html> -- Tioga. Create plots using
28
- Ruby and TeX.
29
-
30
- <br/>
31
- <br/>
32
- <br/>
33
- <br/>
34
- <br/>
35
- <br/>
@@ -1,71 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
- <html xmlns="http://www.w3.org/1999/xhtml">
3
- <head>
4
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
5
- <link type="text/css" media="screen" rel="stylesheet" href="style.css" />
6
- <title>ruby-opengl -- {{title}}</title>
7
- </head>
8
-
9
- <body>
10
-
11
- <div id="container">
12
-
13
- <div id="header">
14
- <em>ruby-opengl</em>
15
- </div>
16
-
17
- <ul id="tabnav">
18
- <li><a href="./index.html">Home</a></li>
19
- <li><a href="./tutorial.html">Tutorial</a></li>
20
- <li><a href="./build_install.html">Build/Install</a></li>
21
- <li><a href="./roadmap.html">Roadmap</a></li>
22
- <li><a href="./requirements_and_design.html">Req's doc</a></li>
23
- <li><a href="./history.html">History</a></li>
24
- </ul>
25
-
26
- <div id="sidebar">
27
- <img src="./images/ogl.jpg">
28
- <h3>Contact</h3>
29
- <ul>
30
- <li><a href="http://rubyforge.org/mail/?group_id=2103">Mailing list</a></li>
31
- <li><a href="http://rubyforge.org/tracker/?atid=8185&amp;group_id=2103&amp;func=browse">Bug tracker</a></li>
32
- <li><a href="http://rubyforge.org/projects/ruby-opengl">Project page</a></li>
33
- </ul>
34
- <h3>Download</h3>
35
- <ul>
36
- <li><a href="http://rubyforge.org/frs/?group_id=2103">Releases</a></li>
37
- <li><a href="http://rubyforge.org/scm/?group_id=2103">SVN</a></li>
38
- </ul>
39
- <h3>Other docs</h3>
40
- <ul>
41
- <li><a href="./extensions.html">Extension support</a></li>
42
- <li><a href="./thanks.html">Thanks</a></li>
43
- <li><a href="./scientific_use.html">Scientific use</a></li>
44
- </ul>
45
-
46
- <h3>Links</h3>
47
- <ul>
48
- <li><a href="http://www.opengl.org/">OpenGL</a></li>
49
- <li><a href="http://www.mesa3d.org/">Mesa</a></li>
50
- <li><a href="http://freeglut.sourceforge.net/">freeglut</a></li>
51
- <li><a href="http://rubyforge.org/projects/ruby-ftgl/">ruby-ftgl</a></li>
52
- <li><a href="http://www.rubygarden.org/ruby?OpenGL">Ruby wiki GL page</a></li>
53
- <li><a href="http://rubygame.sourceforge.net">RubyGame</a></li>
54
- </ul>
55
- </div>
56
-
57
- <div id="content">
58
-
59
- {{content}}
60
-
61
- </div>
62
- <div id="footer">
63
- <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0</a> |
64
- Copyright &copy; <a href="#">Alain Hoang</a> |
65
- Design by <a href="http://www.jdavidmacor.com">super j man</a></p>
66
- </div>
67
-
68
- </div>
69
-
70
- </body>
71
- </html>
@@ -1,29 +0,0 @@
1
- Thank you
2
- ---------
3
-
4
- Aside from big thank-you's to the core devs, special thanks also goes to:
5
-
6
- * Bill Kelly -- provided some pilot code changing how users can call method and constant names.
7
- * Ilmari Heikkinen -- provided code for changing how users can call method and constant names.
8
- * James Adam -- Mac OS X fixes
9
- * Tony Hursh -- Mac OS X glut build tweak
10
- * Sean Long -- More Mac OS X fixes
11
- * John Gabriele -- Numerous fixes, documentation, and project support
12
- * Ronald Pijnacker -- Windows support and bugfixes
13
- * **Yoshi** -- providing ruby-opengl-0.32g from which to work off of.
14
-
15
- <br/>
16
- <br/>
17
- <br/>
18
- <br/>
19
- <br/>
20
- <br/>
21
- <br/>
22
- <br/>
23
- <br/>
24
- <br/>
25
- <br/>
26
- <br/>
27
- <br/>
28
- <br/>
29
- <br/>
@@ -1,469 +0,0 @@
1
- Usage Tutorial
2
- ==============
3
- This page should serve as tutorial and also as reference to Ruby bindings for OpenGL
4
- language. It is assumed that you have basic understanding of both OpenGL and Ruby.
5
-
6
- If you are new to OpenGL, you can start by visiting [OpenGL homepage](http://www.opengl.org)
7
- , reading the [OpenGL Programming Guide](http://opengl.org/documentation/books/#the_opengl_programming_guide_the_official_guide_to_learning_opengl_version) (also known as Red Book) or going to [NeHe's tutorials page](http://nehe.gamedev.net/).
8
-
9
- If you are new to Ruby, [the ruby-lang website](http://www.ruby-lang.org/en/documentation/) contains lots of
10
- documentation and manuals for Ruby.
11
-
12
- Table of Contents
13
- ==============
14
- Basics:
15
- * [Naming Conventions](#naming_conventions)<br/>
16
- * [Function parameters](#function_parameters)<br/>
17
- * [Return values](#return_values)<br/>
18
- * [Matrices](#matrices)<br/>
19
- * [Textures and other raw data](#textures)<br/>
20
- * [Error Checking](#error_checking)<br/>
21
- * [Examples](#examples)<br/>
22
-
23
- Advanced stuff:
24
- * [OpenGL version and Extensions](#extensions)<br/>
25
- * [Selection and Feedback queries](#selection_feedback)<br/>
26
- * [Vertex Arrays](#vertex_arrays)<br/>
27
- * [Buffer Objects](#buffer_objects)<br/>
28
- * [GLUT, SDL, GLFW..](#glut_sdl)<br/>
29
- * [GLUT callbacks](#glut_callbacks)<br/>
30
- * [Internals](#internals)<br/>
31
-
32
- API reference:
33
- * TODO
34
-
35
- <a name="naming_conventions"></a>
36
- Naming conventions
37
- ------------------
38
-
39
- The bindings contains three modules:
40
- * 'Gl' - OpenGL functions itself
41
- * 'Glu' - OpenGL Utility Library API - higher-level drawing routines, NURBS etc.
42
- * 'Glut' - OpenGL Utility Toolkit - low level functions such as creating OpenGL
43
- context, opening window or handling user input
44
-
45
- You can import all three modules by calling
46
-
47
- {{ruby}}
48
- require 'opengl'
49
-
50
- You can also load the modules separately by using:
51
-
52
- {{ruby}}
53
- require 'gl'
54
- require 'glu'
55
- require 'glut'
56
-
57
- The functions and constants are named the same as their C counterparts:
58
-
59
- {{ruby}}
60
- require 'opengl'
61
- ...
62
- Gl.glFooBar( Gl::GL_FOO_BAR )
63
- Glu.gluFooBar( Glu::GLU_FOO_BAR )
64
- Glut.glutFooBar( Glut::GLUT_FOO_BAR )
65
-
66
- This is the 'full' syntax, usefull when you are expecting name clashes
67
- with other modules, or just want to be formal ;) More often, you will
68
- want to use the 'C-style' syntax, which you can accomplish by using 'include'
69
- to export the module functions and constants to global namespace:
70
-
71
- {{ruby}}
72
- require 'opengl'
73
- include Gl,Glu,Glut
74
- ...
75
- glFooBar( GL_FOO_BAR )
76
- gluFooBar( GLU_FOO_BAR )
77
- glutFooBar( GLUT_FOO_BAR )
78
-
79
- Finally, you can use the 'old' syntax:
80
-
81
- {{ruby}}
82
- require 'opengl'
83
- ...
84
- # Note the missing prefixes in functions and constants
85
- # and also capitalization of module names
86
- GL.FooBar( GL::FOO_BAR )
87
- GLU.FooBar( GLU::FOO_BAR )
88
- GLUT.FooBar( GLUT::FOO_BAR )
89
-
90
- This syntax was used by previous ruby-opengl versions; some people also
91
- consider it as being more in the spirit of OO programming. It has one
92
- downside though - due to Ruby's naming scheme, you cannot use constants
93
- which begins with number, e.g. GL_2D would under this syntax be (GL::)2D
94
- which is illegal.
95
-
96
- All three variants of syntax will continue to be supported in future,
97
- so it's up to you which one you choose to use.
98
-
99
- The rest of this tutorial will use the C syntax.
100
-
101
- Calling syntax
102
- --------------
103
- <a name="function_parameters"></a>
104
- Function parameters
105
- --------------
106
- For most types the ruby syntax follows the C API. If needed, ruby will do
107
- automatic parameter conversion to required type if possible. Example:
108
-
109
- {{ruby}}
110
- glVertex3f( 1.0, 1.0, 1.0 ) # matches C syntax
111
- glVertex3f( 1, 1, 1 ) # equivalent to the above
112
- glVertex3f( "string", 1, 1 ) # raises TypeError exception
113
-
114
- Arrays are passed/received as Ruby arrays:
115
-
116
- {{ruby}}
117
- vertex = [ 1, 1, 1 ]
118
- glVertex3fv( vertex )
119
-
120
- For functions with multiple parameter-number variations (glVertex,glColor,...)
121
- we define 'overloaded' functions, as in:
122
-
123
- {{ruby}}
124
- glVertexf( 1, 1 ) # will call glVertex2f()
125
- glVertexf( 1, 1, 1 ) # will call glVertex3f()
126
- glVertexf( 1, 1, 1, 1 ) # will call glVertex4f()
127
- glVertexi( 1, 1 ) # will call glVertex2i()
128
- ...
129
- # and so on
130
-
131
- <a name="return_values"></a>
132
- Return values
133
- -------------
134
- In C, OpenGL functions rarely return values directly, instead you pass in pointer to
135
- preallocated buffer and they will fill it with values; sometimes you have to even query
136
- how big buffer you'll need to allocate. Ruby does this all for you, returning either single
137
- value or array:
138
-
139
- {{ruby}}
140
- glColor4f( 1.0, 1.0, 1.0, 1.0 )
141
- ...
142
- color = glGetDoublev(GL_CURRENT_COLOR)
143
- p color # will be [1.0,1.0,1.0,1.0]
144
-
145
- <a name="matrices"></a>
146
- Matrices
147
- -------------
148
- Matrices are passed and received as ruby array, or as ruby Matrix objects:
149
-
150
- {{ruby}}
151
- matrix_a = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
152
- matrix_b = [ [ 0, 1, 2, 3 ],
153
- [ 4, 5, 6, 7 ],
154
- [ 8, 9,10,11 ],
155
- [ 12,13,14,15 ] ]
156
- matrix_c = Matrix.rows( [ [ 0, 1, 2, 3 ],
157
- [ 4, 5, 6, 7 ],
158
- [ 8, 9,10,11 ],
159
- [ 12,13,14,15 ] ] )
160
- ...
161
- glLoadMatrixf(matrix_a)
162
- glLoadMatrixf(matrix_b)
163
- glLoadMatrixf(matrix_c) # same result
164
-
165
- You may also create your own matrix class and pass it this way, provided that it
166
- is convertible to array (has 'to_a' method).
167
-
168
- Note that as OpenGL uses column-major
169
- notation for matrices, you may need to call transpose() when working with
170
- row-major matrices or arrays in ruby.
171
-
172
- <a name="textures"></a>
173
- Textures and other raw data
174
- -------------
175
- Data for textures, arrays, buffers etc. can be specified either as ruby arrays or directly as raw packed strings -
176
- strings that contains their direct memory representation (just like C arrays). If you need to convert between
177
- ruby arrays and these strings, use ruby Array#pack() and String#unpack() functions.
178
- Example:
179
-
180
- {{ruby}}
181
- # create texture, 2x2 pixels,
182
- # 3 components (R,G,B) for each pixel as floats
183
- texture = [
184
- 1.0, 0.0, 0.0, # 1st pixel, red
185
- 0.0, 1.0, 0.0, # 2nd pixel, green
186
- 0.0, 0.0, 1.0, # 3rd pixel, blue
187
- 1.0, 1.0, 1.0 # 4th pixel, white
188
- ]
189
- # convert it to string
190
- # f = native float representation
191
- # * = convert all values in the array the same way
192
- data = texture.pack("f*")
193
- ...
194
- glTexImage2D(
195
- GL_TEXTURE_2D, # target
196
- 0, # mipmap level,
197
- GL_RGB8, # internal format
198
- 2, 2, # width, height
199
- 0, # border = no
200
- GL_RGB, # components per each pixel
201
- GL_FLOAT, # component type - floats
202
- data # the packed data
203
- )
204
-
205
- Reverse works just the same:
206
-
207
- {{ruby}}
208
- ...
209
- data = glGetTexImage( # returns the packed data as string
210
- GL_TEXTURE_2D, # target
211
- 0, # mipmap level
212
- GL_RGB, # components per pixel
213
- GL_FLOAT # component type
214
- )
215
- # now convert it to ruby array
216
- texture = data.unpack("f*")
217
- ...
218
-
219
- For storage, packed strings are more memory efficient than ruby arrays, but
220
- cannot be easily changed or manipulated.
221
-
222
- <a name="error_checking"></a>
223
- Error Checking
224
- --------------
225
- Starting with version 0.60.0, ruby-opengl performs automatic checking of OpenGL and GLU errors.
226
- Functions:
227
-
228
- {{ruby}}
229
- Gl.enable_error_checking
230
- Gl.disable_error_checking
231
- Gl.is_error_checking_enabled? # true/false
232
-
233
- When the checking is enabled (default), glGetError() is executed after each OpenGL call, and should error
234
- occur, Gl::Error exception is raised:
235
-
236
- {{ruby}}
237
- Gl.enable_error_checking
238
- ...
239
- begin
240
- ...
241
- glEnable(GL_TRUE) # will raise exception
242
- ...
243
- rescue Gl::Error => err
244
- # err.id contains the OpenGL error ID
245
- if (err.id == GL_INVALID_ENUM)
246
- puts "Oh noes! You used invalid enum!"
247
- ...
248
- end
249
- ...
250
- end
251
-
252
- Some GLU functions may also throw Glu::Error - the handling is the same as above.
253
-
254
- It is usually good idea to leave error checking on for all your code, as OpenGL errors have habit to pop-up in
255
- unexpected places. For now there is no measurable performance hit for error checking, although this may depend
256
- on your graphic drivers implementation.
257
-
258
- <a name="examples"></a>
259
- The Examples
260
- -----------
261
-
262
- Various examples are in 'examples' directory of the bindings. To run them, manually pass them to `ruby` like:
263
-
264
- ruby some_sample.rb
265
-
266
- On windows, you may want to use 'rubyw' instead, which displays the standard output window
267
- as some examples use the console for usage info etc.
268
-
269
- If you get 'opengl not found' error, and you installed ruby-opengl from gems, your
270
- shell or ruby installation is probably not configured to use the gems; in that case type:
271
-
272
- ruby -rubygems some_sample.rb
273
-
274
- The `README` file in the `examples` directory contains some notes on the examples.
275
-
276
- <a name="extensions"></a>
277
- OpenGL Version and Extensions
278
- -----------
279
- To query for available OpenGL version or OpenGL extension, use Gl.is_available? function:
280
-
281
- {{ruby}}
282
- # true if OpenGL version is 2.0 or later is available
283
- Gl.is_available?(2.0)
284
- ...
285
- # returns true if GL_ARB_shadow is available on this system
286
- Gl.is_available?("GL_ARB_shadow")
287
-
288
- For list of what extensions are supported in ruby-opengl see this [page](extensions.html)
289
-
290
- The extensions' function names once again follows the C API. Some extensions were over time
291
- promoted to ARB or even to OpenGL core, retaining their function names just with suffix changed
292
- or removed. However sometimes the functions semantics was changed in the process, so to avoid
293
- confusion, ruby-opengl bindings will strictly adhere to the C naming, e.g. :
294
-
295
- {{ruby}}
296
- # will call the function from GL_ARB_transpose_matrix extension
297
- glLoadTransposeMatrixfARB(matrix)
298
- ...
299
- # will call the function from OpenGL 1.3
300
- glLoadTransposeMatrixf(matrix)
301
-
302
- <b>Note:</b> ruby-opengl is compiled against OpenGL 1.1, and all functions and enums from later
303
- versions of OpenGL and from extensions are loaded dynamically at runtime. That means that all
304
- of OpenGL 2.1 and supported extensions are available even if the ruby-opengl bindings are
305
- compiled on platform which lacks proper libraries or headers (like for example Windows without
306
- installed graphic drivers). This should ease binary-only distribution and application packaging.
307
-
308
-
309
- <a name="selection_feedback"></a>
310
- Selection/Feedback queries
311
- -----------
312
- Querying selection and feedback is different from C. Example:
313
-
314
- {{ruby}}
315
- # this will create selection buffer 512*sizeof(GLuint) long
316
- buf = glselectbuffer(512)
317
- # enter feedback mode
318
- glRenderMode(GL_SELECT)
319
- ... # draw something here
320
- # return to render mode
321
- count = glRenderMode(GL_RENDER)
322
- # at this point the buf string is freezed and contains
323
- # the selection data, which you can recover with unpack
324
- # function
325
- data = buf.unpack("I*") # I for unsigned integer
326
- # also, next call to glRenderMode(GL_SELECT) will overwrite
327
- # the 'buf' buffer with new data
328
-
329
- The feedback query follows the same pattern, only the data are stored
330
- as floats.
331
-
332
- <a name="vertex_arrays"></a>
333
- Vertex Arrays
334
- -----------
335
- In current state, vertex arrays are not very efficient in ruby-opengl, as it is not possible to change
336
- the array content once it is specified, and there is overhead for converting between ruby and C representation
337
- of numbers. Using display lists for static and immediate mode for dynamic objects is recommended instead.
338
-
339
- You can specify the data the same way as [texture data](#textures). Example:
340
-
341
- {{ruby}}
342
- normals = [0,1,0, 1,0,0, 1,1,1]
343
- glNormalPointer(GL_FLOAT,0,normals)
344
- ...
345
- glEnable(GL_NORMAL_ARRAY)
346
- glDrawArrays(...)
347
- ...
348
-
349
- This applies to all *pointer functions. glGetPointerv will return reference to the frozen string
350
- previously specified.
351
-
352
- <a name="buffer_objects"></a>
353
- Buffer Objects
354
- -----------
355
- Once again, in current state buffer objects (VBOs in particular) are not very efficient in ruby-opengl.
356
- Unlike textures and vertex arrays, the data for buffers *must* be prepacked by using .pack() function,
357
- as buffers does not retain information about the storage type. Mapping of the buffer afterwards is read-only.
358
-
359
- Like in C, buffer binding affects some functions in way that if particular buffer is bound, the related
360
- functions (for example glTexImage) take integer offset in place of data string argument. This is also true
361
- for getter functions (e.g. glGetTexImage) - instead of returning the data string, they take offset as they're
362
- last argument (so in ruby they take one extra argument), and will write the data in the bound buffer as expected.
363
-
364
- VBO example:
365
-
366
- {{ruby}}
367
- # specify 3 vertices, 2*float each
368
- data = [0,0, 0,1, 1,1].pack("f*")
369
- ...
370
- # generate buffer name
371
- buffers = glGenBuffers(1)
372
- # bind to the name to ARRAY buffer for vertex array
373
- glBindBuffer(GL_ARRAY_BUFFER,buffers[0])
374
- # here the data is specified, size is n*sizeof(float)
375
- # note that you don't get to specify type, as buffers
376
- # operate on byte level
377
- glBufferData(GL_ARRAY_BUFFER,6*4,data,GL_DYNAMIC_DRAW)
378
- ...
379
- # here instead of specyfing the data, you pass '0' (or
380
- # positive integer) as offset to the bound buffer
381
- glVertexPointer(2,GL_FLOAT,0,0)
382
- ...
383
- glEnableClientState(GL_VERTEX_ARRAY)
384
- ...
385
-
386
- <a name="glut_sdl"></a>
387
- GLUT, SDL, GLFW..
388
- ---------
389
- When it comes to low-level task like GL window creation, input and event handling, the first choice is GLUT,
390
- as it is readilly available alongside OpenGL. However both GLUT itself and its implementations
391
- have their drawbacks, and for that and other reasons there are number of replacement libraries.
392
- You can use any of them with ruby-opengl (as long as there are ruby bindings for them).
393
-
394
- Here is example for [SDL](http://www.kmc.gr.jp/~ohai/index.en.html):
395
-
396
- {{ruby}}
397
- require 'opengl'
398
- require 'sdl'
399
- # init
400
- SDL.init(SDL::INIT_VIDEO)
401
- SDL.setGLAttr(SDL::GL_DOUBLEBUFFER,1)
402
- SDL.setVideoMode(512,512,32,SDL::OPENGL)
403
- ...
404
- Gl.glVertex3f(1.0,0.0,0.0)
405
- ...
406
- SDL.GLSwapBuffers()
407
- ...
408
-
409
- and another example for [GLFW](http://ruby-glfw.rubyforge.org/):
410
-
411
- {{ruby}}
412
- require 'opengl'
413
- require 'glfw'
414
- # init
415
- Glfw.glfwOpenWindow( 500,500, 0,0,0,0, 32,0, Glfw::GLFW_WINDOW )
416
- ...
417
- Gl.glVertex3f(1.0,0.0,0.0)
418
- ...
419
- Glfw.glfwSwapBuffers()
420
- ...
421
-
422
- <a name="glut_callbacks"></a>
423
- GLUT callbacks
424
- --------------
425
-
426
- The GLUT callback functions are specified as Proc objects, which you can
427
- either create with lambda as:
428
-
429
- {{ruby}}
430
- reshape = lambda do |w, h|
431
- ...
432
- end
433
- ...
434
- glutReshapeFunc( reshape )
435
-
436
- or by conversion from normal functions:
437
-
438
- {{ruby}}
439
- def reshape(w,h)
440
- ...
441
- end
442
- ...
443
- glutReshapeFunc( method("reshape").to_proc )
444
-
445
- Note: An older notation you'll see instead of `lambda` is `proc`. The
446
- PickAxe v2 notes that `proc` is "mildly deprecated" in favor of `lambda`.
447
- You'll also sometimes see `Proc.new` used in place of either. Pages 359-360 of
448
- PickAxe v2 describe the differences between using `lambda` and `Proc.new`,
449
- but for our purposes either will be fine.
450
-
451
- <a name="internals"></a>
452
- Internals
453
- ---------
454
-
455
- The directory structure follows current Ruby standards, with a few
456
- extra directories added.
457
-
458
- * `doc/` -- Contains documentation for the project (from which this
459
- website is generated).
460
- * `examples/` -- Example programs.
461
- * `ext/` -- Contains subdirectories, one for each of the three extension
462
- modules (gl, glu, glut). Herein are the files needed to compile the extension
463
- modules.
464
- * `lib/` -- Files that the user is meant to `require` in their own code.
465
- * `test/` -- Contains automatic testsuite for the bindings
466
- * `utils` -- Some utility scripts used to help generate code, documentation
467
- and website.
468
- * `website` -- After running `rake gen_website` this directory will contain
469
- the ruby-opengl website.