ruby-opengl 0.60.1 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. metadata +36 -186
  2. data/Rakefile +0 -168
  3. data/doc/build_install.txt +0 -122
  4. data/doc/extensions.txt +0 -556
  5. data/doc/extensions.txt.in +0 -348
  6. data/doc/history.txt +0 -66
  7. data/doc/requirements_and_design.txt +0 -117
  8. data/doc/roadmap.txt +0 -28
  9. data/doc/scientific_use.txt +0 -35
  10. data/doc/supplies/page_template.html +0 -71
  11. data/doc/thanks.txt +0 -29
  12. data/doc/tutorial.txt +0 -469
  13. data/examples/NeHe/nehe_lesson02.rb +0 -117
  14. data/examples/NeHe/nehe_lesson03.rb +0 -122
  15. data/examples/NeHe/nehe_lesson04.rb +0 -133
  16. data/examples/NeHe/nehe_lesson05.rb +0 -186
  17. data/examples/NeHe/nehe_lesson36.rb +0 -303
  18. data/examples/OrangeBook/3Dlabs-License.txt +0 -33
  19. data/examples/OrangeBook/brick.frag +0 -36
  20. data/examples/OrangeBook/brick.rb +0 -376
  21. data/examples/OrangeBook/brick.vert +0 -41
  22. data/examples/OrangeBook/particle.frag +0 -17
  23. data/examples/OrangeBook/particle.rb +0 -406
  24. data/examples/OrangeBook/particle.vert +0 -38
  25. data/examples/README +0 -16
  26. data/examples/RedBook/aapoly.rb +0 -142
  27. data/examples/RedBook/aargb.rb +0 -119
  28. data/examples/RedBook/accanti.rb +0 -162
  29. data/examples/RedBook/accpersp.rb +0 -215
  30. data/examples/RedBook/alpha.rb +0 -123
  31. data/examples/RedBook/alpha3D.rb +0 -158
  32. data/examples/RedBook/bezcurve.rb +0 -105
  33. data/examples/RedBook/bezmesh.rb +0 -137
  34. data/examples/RedBook/checker.rb +0 -124
  35. data/examples/RedBook/clip.rb +0 -95
  36. data/examples/RedBook/colormat.rb +0 -135
  37. data/examples/RedBook/cube.rb +0 -69
  38. data/examples/RedBook/depthcue.rb +0 -99
  39. data/examples/RedBook/dof.rb +0 -205
  40. data/examples/RedBook/double.rb +0 -105
  41. data/examples/RedBook/drawf.rb +0 -91
  42. data/examples/RedBook/feedback.rb +0 -145
  43. data/examples/RedBook/fog.rb +0 -167
  44. data/examples/RedBook/font.rb +0 -151
  45. data/examples/RedBook/hello.rb +0 -79
  46. data/examples/RedBook/image.rb +0 -137
  47. data/examples/RedBook/jitter.rb +0 -207
  48. data/examples/RedBook/lines.rb +0 -128
  49. data/examples/RedBook/list.rb +0 -111
  50. data/examples/RedBook/material.rb +0 -275
  51. data/examples/RedBook/mipmap.rb +0 -156
  52. data/examples/RedBook/model.rb +0 -113
  53. data/examples/RedBook/movelight.rb +0 -132
  54. data/examples/RedBook/pickdepth.rb +0 -179
  55. data/examples/RedBook/planet.rb +0 -108
  56. data/examples/RedBook/quadric.rb +0 -158
  57. data/examples/RedBook/robot.rb +0 -115
  58. data/examples/RedBook/select.rb +0 -196
  59. data/examples/RedBook/smooth.rb +0 -95
  60. data/examples/RedBook/stencil.rb +0 -163
  61. data/examples/RedBook/stroke.rb +0 -167
  62. data/examples/RedBook/surface.rb +0 -166
  63. data/examples/RedBook/teaambient.rb +0 -132
  64. data/examples/RedBook/teapots.rb +0 -182
  65. data/examples/RedBook/tess.rb +0 -183
  66. data/examples/RedBook/texbind.rb +0 -147
  67. data/examples/RedBook/texgen.rb +0 -169
  68. data/examples/RedBook/texturesurf.rb +0 -128
  69. data/examples/RedBook/varray.rb +0 -159
  70. data/examples/RedBook/wrap.rb +0 -148
  71. data/examples/misc/OGLBench.rb +0 -337
  72. data/examples/misc/anisotropic.rb +0 -194
  73. data/examples/misc/fbo_test.rb +0 -356
  74. data/examples/misc/font-glut.rb +0 -46
  75. data/examples/misc/glfwtest.rb +0 -30
  76. data/examples/misc/plane.rb +0 -161
  77. data/examples/misc/readpixel.rb +0 -65
  78. data/examples/misc/sdltest.rb +0 -34
  79. data/examples/misc/trislam.rb +0 -828
  80. data/ext/common/common.h +0 -423
  81. data/ext/common/conv.h +0 -244
  82. data/ext/common/funcdef.h +0 -280
  83. data/ext/common/gl-enums.h +0 -10031
  84. data/ext/common/gl-error.h +0 -23
  85. data/ext/common/gl-types.h +0 -61
  86. data/ext/common/glu-enums.h +0 -463
  87. data/ext/gl/gl-1.0-1.1.c +0 -2817
  88. data/ext/gl/gl-1.2.c +0 -814
  89. data/ext/gl/gl-1.3.c +0 -444
  90. data/ext/gl/gl-1.4.c +0 -349
  91. data/ext/gl/gl-1.5.c +0 -225
  92. data/ext/gl/gl-2.0.c +0 -657
  93. data/ext/gl/gl-2.1.c +0 -57
  94. data/ext/gl/gl-enums.c +0 -3354
  95. data/ext/gl/gl-error.c +0 -104
  96. data/ext/gl/gl-ext-3dfx.c +0 -27
  97. data/ext/gl/gl-ext-arb.c +0 -866
  98. data/ext/gl/gl-ext-ati.c +0 -41
  99. data/ext/gl/gl-ext-ext.c +0 -890
  100. data/ext/gl/gl-ext-gremedy.c +0 -41
  101. data/ext/gl/gl-ext-nv.c +0 -679
  102. data/ext/gl/gl.c +0 -214
  103. data/ext/gl/mkrf_conf.rb +0 -34
  104. data/ext/glu/glu-enums.c +0 -164
  105. data/ext/glu/glu.c +0 -1530
  106. data/ext/glu/mkrf_conf.rb +0 -35
  107. data/ext/glut/glut.c +0 -1623
  108. data/ext/glut/mkrf_conf.rb +0 -37
  109. data/lib/opengl.rb +0 -84
  110. data/test/README +0 -10
  111. data/test/tc_common.rb +0 -98
  112. data/test/tc_ext_arb.rb +0 -467
  113. data/test/tc_ext_ati.rb +0 -33
  114. data/test/tc_ext_ext.rb +0 -551
  115. data/test/tc_ext_gremedy.rb +0 -36
  116. data/test/tc_ext_nv.rb +0 -357
  117. data/test/tc_func_10_11.rb +0 -1281
  118. data/test/tc_func_12.rb +0 -186
  119. data/test/tc_func_13.rb +0 -229
  120. data/test/tc_func_14.rb +0 -197
  121. data/test/tc_func_15.rb +0 -270
  122. data/test/tc_func_20.rb +0 -346
  123. data/test/tc_func_21.rb +0 -541
  124. data/test/tc_glu.rb +0 -310
  125. data/test/tc_include_gl.rb +0 -35
  126. data/test/tc_misc.rb +0 -54
  127. data/test/tc_require_gl.rb +0 -34
data/doc/roadmap.txt DELETED
@@ -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/>
data/doc/scientific_use.txt DELETED
@@ -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/>
data/doc/supplies/page_template.html DELETED
@@ -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>
data/doc/thanks.txt DELETED
@@ -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/>
data/doc/tutorial.txt DELETED
@@ -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.