1#lang scribble/doc
2@(require "common.rkt" scribble/eval (for-syntax racket/base))
3
4@title[#:tag "main"]{Racket-Style OpenGL}
5
6@defmodule[sgl]
7
8The functions in @racketmodname[sgl] use Racket style names instead of
9C style names.  To convert a C OpenGL name to a Racket OpenGL name,
10change the @tt{gl} prefix to @racketidfont{gl-}, separate adjacent
11words with hyphens, and convert to all lower case.  Functions that
12have several variants to accommodate different numbers and types of
13arguments are collapsed into one or two functions in
14@racketmodname[sgl].  For example, @racketmodname[sgl] provides two
15vertex functions: @racket[vertex] and @racket[vertex-v].  The
16@racket[vertex] function accepts 2, 3 or 4 numerical arguments, and
17the @racket[vertex-v] function accepts @racket[gl-vector]s of length
182, 3 or 4.  The C language OpenGL interface, in contrast, has 24
19vertex functions: @tt{glVertex3i}, @tt{glVertex4fv}, etc.
20
21Functions in @racketmodname[sgl] take symbols instead of integers for
22@tt{GLenum} arguments.  Each function checks that the given symbol is
23an acceptable argument and raises an exception if it is not.  Given
24the name of a C-language @tt{#define} constant, determine the
25corresponding symbolic argument by removing the leading @tt{GL_},
26converting the letters to lower-case and replacing each @tt{_} with
27@racketidfont{-}.  For example, @tt{GL_TRIANGLES} becomes
28@racket['triangles], and @tt{GL_TRIANGLE_STRIP} becomes
29@racket['triangle-strip].  Additionally, the functions check the
30length of any array arguments to ensure that OpenGL does not attempt
31to write or read after the array.
32
33The @racketmodname[sgl] module is not as complete as the
34@racketmodname[sgl/gl] module.
35
36@as-examples[
37@racketblock[
38(require sgl sgl/gl-vectors)
39(gl-begin 'triangles)
40(gl-vertex 1 2 3)
41(gl-vertex-v (gl-float-vector 1 2 3 4))
42(gl-end)
43]]
44
45@defstruct[gl-selection-record ([min-z real?] [max-z real?] [stack ....])]{
46
47Represents a selection.}
48
49@(define-syntax-rule (def-racket-gl (id ...) body ...)
50   @deftogether[(
51    @defthing[id procedure?] ...
52   ) body ...])
53
54@def-racket-gl[(
55gl-accum
56gl-active-texture
57gl-alpha-func
58gl-begin
59gl-begin-query
60gl-blend-color
61gl-blend-equation
62gl-blend-func
63gl-blend-func-separate
64gl-call-list
65gl-check-extension
66gl-clear
67gl-clear-accum
68gl-clear-color
69gl-clear-depth
70gl-clear-index
71gl-clear-stencil
72gl-clip-plane
73gl-color
74gl-color-mask
75gl-color-material
76gl-color-v
77gl-copy-pixels
78gl-cull-face
79gl-cylinder
80gl-delete-lists
81gl-delete-queries
82gl-depth-func
83gl-depth-mask
84gl-depth-range
85gl-disable
86gl-disk
87gl-edge-flag
88gl-enable
89gl-end
90gl-end-list
91gl-end-query
92gl-eval-coord
93gl-eval-coord-v
94gl-eval-mesh
95gl-eval-point
96gl-feedback-buffer->gl-float-vector
97gl-finish
98gl-flush
99gl-front-face
100gl-frustum
101gl-gen-lists
102gl-gen-queries
103gl-get-error
104gl-get-string
105gl-hint
106gl-index
107gl-index-mask
108gl-index-v
109gl-init-names
110gl-is-buffer
111gl-is-enabled
112gl-is-list
113gl-is-query
114gl-light
115gl-light-model
116gl-light-model-v
117gl-light-v
118gl-line-stipple
119gl-line-width
120gl-list-base
121gl-load-identity
122gl-load-matrix
123gl-load-name
124gl-load-transpose-matrix
125gl-look-at
126gl-map-grid
127gl-material
128gl-material-v
129gl-matrix-mode
130gl-mult-matrix
131gl-mult-transpose-matrix
132gl-multi-tex-coord
133gl-multi-tex-coord-v
134gl-new-list
135gl-new-quadric
136gl-normal
137gl-normal-v
138gl-ortho
139gl-ortho-2d
140gl-partial-disk
141gl-pass-through
142gl-perspective
143gl-pick-matrix
144gl-pixel-store
145gl-point-parameter
146gl-point-parameter-v
147gl-point-size
148gl-polygon-mode
149gl-polygon-offset
150gl-pop-attrib
151gl-pop-client-attrib
152gl-pop-matrix
153gl-pop-name
154gl-project
155gl-push-matrix
156gl-push-name
157gl-quadric-draw-style
158gl-quadric-normals
159gl-quadric-orientation
160gl-quadric-texture
161gl-raster-pos
162gl-raster-pos-v
163gl-rect
164gl-rect-v
165gl-render-mode
166gl-rotate
167gl-sample-coverage
168gl-scale
169gl-scissor
170gl-secondary-color
171gl-secondary-color-v
172gl-select-buffer->gl-uint-vector
173gl-shade-model
174gl-sphere
175gl-stencil-func
176gl-stencil-mask
177gl-stencil-op
178gl-tex-coord
179gl-tex-coord-v
180gl-tex-gen
181gl-tex-gen-v
182gl-translate
183gl-u-get-string
184gl-un-project
185gl-un-project4
186gl-vertex
187gl-vertex-v
188gl-viewport
189gl-window-pos
190gl-window-pos-v
191)]{
192
193Racket-style variants of the OpenGL functions.}
194
195
196@defproc[(gl-process-selection [vec gl-uint-vector?]
197                               [hits exact-nonnegative-integer?])
198         (listof gl-selection-record?)]{
199
200Parses the contents of @racket[vec] from the format used by
201@racket[glSelectBuffer].  The second argument should be the number of
202hits as returned by @racket[glRenderMode].}
203
204
205@defproc[(gl-get-gl-version-number) exact-nonnegative-integer?]{
206
207Returns the run-time OpenGL version number as an integer: @racket[10],
208@racket[11], @racket[12], @racket[13], @racket[14], @racket[15], or
209@racket[20].}
210
211@defproc[(gl-get-glu-version-number) exact-nonnegative-integer?]{
212
213Returns the run-time GLU version number as an integer: @racket[10],
214@racket[11], @racket[12], or @racket[13].}
215