source: project/wiki/eggref/5/glfw3 @ 37371

Last change on this file since 37371 was 37371, checked in by Kooda, 5 months ago

Document glfw3 for CHICKEN 5

File size: 14.0 KB
Line 
1== glfw3
2[[toc:]]
3
4=== Description
5Bindings to the [[https://www.glfw.org/|GLFW]] OpenGL window and event management library, version 3.X. Version 3 of GLFW is not backwards compatible with previous major versions of GLFW.
6
7The CHICKEN 5 port of this egg still needs some work and testing regarding OS X and Windows support.
8
9When using with OpenGL ES, make sure GLFW is appropriately compiled (e.g.: {{cmake -DGLFW_USE_EGL=ON -DGLFW_CLIENT_LIBRARY=glesv2 -DBUILD_SHARED_LIBS=ON}}).
10
11When installing GLFW on OS X through Homebrew, an extra step is needed. Homebrew renames the library’s from the default. You can fix this by creating a link that points to the library that gets installed. E.g. {{sudo ln -s <homebrew-lib-dir>/libglfw3.dylib /usr/local/lib/libglfw.dylib}}
12
13
14=== Requirements
15* Bind
16
17
18=== Documentation
19glfw3 is separated into two modules: {{glfw3-bindingw}} and {{glfw3}}. For almost all purposes, only {{glfw3}} should be needed.
20
21{{glfw3-bindings}} provides direct bindings to GLFW generated by [[https://wiki.call-cc.org/egg/bind|bind]]. Names have been converted from camelCase to hyphenated, with GLFW prefixes removed (e.g. {{glfwGetTimerValue}} becomes {{get-timer-value}}. Constants are lower-cased and surrounded by {{+}}s (e.g. {{GLFW_ALPHA_BITS}} becomes {{+alpha-bits+}}).
22
23{{glfw3}} is the high-level interface that should be used in most cases. At the moment it is largely re-exporting {{glfw3-bindings}}, although many of these functions could still use wrappers (patches welcome!). The not-exactly-the-same-as-the-glfw-api functions are described in the section [[#high-level-interface|High-level interface]].
24
25For information regarding the GLFW API, see the official [[https://www.glfw.org/documentation.html|GLFW documentation]].
26
27
28==== High-level interface
29<procedure> (init)</procedure>
30
31Initializes glfw. Not needed when using {{with-window}}.
32
33<parameter> window</parameter>
34
35Contains the window associated with the current context.
36
37<procedure> (make-context-current WINDOW)</procedure>
38
39Performs {{glfwMakeContextCurrent}} while setting the above {{window}} parameter to the new value.
40
41<procedure> (make-window WIDTH HEIGHT NAME #!key (fullscreen? #f) (swap-interval 1) resizable visible decorated red-bits green-bits blue-bits alpha-bits depth-bits stencil-bits accum-red-bits accum-green-bits accum-blue-bits accum-alpha-bits aux-buffers samples refresh-rate sterio srgb-capable client-api context-version-major context-version-minor context-robustness opengl-forward-compat opengl-debug-context opengl-profile)</procedure>
42
43Create a window with title string {{NAME}} and dimensions {{WIDTH}} by {{HEIGHT}}. The keys correspond to the available [[https://www.glfw.org/docs/latest/window.html#window_hints|GLFW window hints]]. {{resizable}}, {{visible}}, {{decorated}}, {{stereo}}, {{srgb-capable}}, {{opengl-forward-compat}}, {{opengl-debug-context}} accept boolean arguments, while all other accept either an integer or an appropriate GLFW constant as per the documentation.
44
45Sets the current context to the window that was created. The swap interval of the window is set to the value of the{{swap-interval}} key. Finally, this initializes all of the window-specific callbacks.
46
47When using with OS X, make sure you ask for the right context. Only OS X 10.7+ support core contexts, and only limited contexts are supported. See [[https://www.glfw.org/faq.html#41---how-do-i-create-an-opengl-30-context|the GLFW FAQ]]. For instance:
48
49    (make-window WIDTH HEIGHT NAME
50                 context-version-major: 3
51                 context-version-minor: 2
52                 opengl-forward-compat: #t
53                 opengl-profile: +opengl-core-profile+)
54   
55   
56<macro> (with-window (WIDTH HEIGHT NAME . KEYS) BODY ...)</macro>
57
58Initializes GLFW, creates a window as per {{make-window}}, and runs {{BODY}} before cleaning up.
59
60
61==== Callbacks
62{{glfw3}} provides parameters which contain the functions that are called from GLFW callbacks. The GLFW callbacks are initialized to call these parameters when {{init}} and {{make-window}} or {{with-window}} are used, but they can be changed with the callback setter functions.
63
64<parameter> window-position-callback</parameter>
65
66Called when a window is moved. Expects a function with the signature {{(lambda (WINDOW X Y) ...)}}. {{WINDOW}} is the window that was moved. {{X}} and {{Y}} are the coordinates of the upper-left corner of the window.
67
68<parameter> window-size-callback</parameter>
69
70Called when a window is resized. Expects a function with the signature {{(lambda (WINDOW W H) ...)}}. {{WINDOW}} is the window that was resized. {{W}} and {{H}} are the new dimensions  of the window.
71
72<parameter> window-close-callback</parameter>
73
74Called when a window is closed. Expects a function with the signature {{(lambda (WINDOW) ...)}}. {{WINDOW}} is the window that was closed.
75
76<parameter> window-focus-callback</parameter>
77
78Called when a window comes into or goes out of focus. Expects a function with the signature {{(lambda (WINDOW FOCUSED?) ...)}}. {{WINDOW}} is the affected window, while {{FOCUSED?}} is true when the window has been focused and false otherwise.
79
80<parameter> window-iconify-callback</parameter>
81
82Called when a window is iconified or restored. Expects a function with the signature {{(lambda (WINDOW ICONIFIED?) ...)}}. {{WINDOW}} is the affected window, while {{ICONIFIED?}} is true when the window has been iconified and false otherwise.
83
84<parameter> framebuffer-size-callback</parameter>
85
86Called when a framebuffer is resized. Expects a function with the signature {{(lambda (WINDOW W H) ...)}}. {{WINDOW}} is the window whose framebuffer was resized. {{W}} and {{H}} are the new dimensions, in pixels, of the framebuffer.
87
88<parameter> mouse-button-callback</parameter>
89
90Called when a mouse button is pressed or released. Expects a function with the signature {{(lambda (WINDOW BUTTON ACTION MODS) ...)}}. {{WINDOW}} is the window where the button was pressed, {{BUTTON}} is the name of the mouse button (one of {{+mouse-button-1+}} through {{+mouse-button-8+}}, {{+mouse-button-last+}}, {{+mouse-button-left+}}, {{+mouse-button-right+}}, {{+mouse-button-middle+}}), {{ACTION}} is one of {{+press+}} or {{+release+}}, and {{MODS}} is a bit field describing the modifier keys that were held down (any of {{+mod-shift+}}, {{+mod-control+}}, {{+mod-alt+}}, or {{+mod-super+}}).
91
92<parameter> cursor-enter-callback</parameter>
93
94Called when a cursor enters or leaves a window. Expects a function with the signature {{(lambda (WINDOW ENTERED?) ...)}}. {{WINDOW}} is the affected window, and {{ENTERED?}} is true when the window was entered and false otherwise.
95
96<parameter> cursor-position-callback</parameter>
97
98Called when a cursor moves. Expects a function with the signature {{(lambda (WINDOW X Y) ...)}}. {{WINDOW}} is the affected window. {{X}} and {{Y}} is the new coordinates of the cursor.
99
100<parameter> scroll-callback</parameter>
101
102Called when a scroll occurs. Expects a function with the signature {{(lambda (WINDOW X Y) ...)}}. {{WINDOW}} is the affected window. {{X}} and {{Y}} are the scroll offsets.
103
104<parameter> key-callback</parameter>
105
106Called when a key is pressed or released. Expects a function with the signature {{(lambda (WINDOW KEY SCANCODE ACTION MODS) ...)}}. {{WINDOW}} is the window where the button was pressed, {{KEY}} is the name of the key, {{SCANCODE}} is the system-specific scancode of the key, {{ACTION}} is one of {{+press+}}, {{+release+}} or {{+repeat+}}, and {{MODS}} is a bit field describing the modifier keys that were held down (any of {{+mod-shift+}}, {{+mod-control+}}, {{+mod-alt+}}, or {{+mod-super+}}).
107
108<parameter> char-callback</parameter>
109
110Called when character is entered. Expects a function with the signature {{(lambda (WINDOW CHAR) ...)}}. {{WINDOW}} is the affected window, and  {{CHAR}} is the unicode code point of the character.
111
112<parameter> char-mods-callback</parameter>
113
114Called when character is entered, but also includes modifiers that were active when the character was entered. Expects a function with the signature {{(lambda (WINDOW CHAR MODS) ...)}}. {{WINDOW}} is the affected window, and  {{CHAR}} is the unicode code point of the character, {{MODS}} is the bitfield of the modifiers that were active.
115
116<parameter> monitor-callback</parameter>
117
118Called when a monitor is connected or disconnected. Expects a function with the signature {{(lambda (MONITOR EVENT) ...)}}. {{MONITOR}} is a pointer to the affected monitor, {{EVENT}} is either {{+connected+}} or {{+disconnected+}}.
119
120<parameter> joystick-callback</parameter>
121
122Called when a joystick is plugged-in or plugged-out. Expects a function with the signature {{(lambda (JOYSTICK EVENT) ...)}}. {{JOYSTICK}} is an integer representing the joystick, {{EVENT}} is either {{+connected+}} or {{+disconnected+}}.
123
124<procedure> (set-window-position-callback! [WINDOW [CALLBACK]])</procedure>
125<procedure> (set-window-size-callback! [WINDOW [CALLBACK]])</procedure>
126<procedure> (set-window-close-callback! [WINDOW [CALLBACK]])</procedure>
127<procedure> (set-window-focus-callback! [WINDOW [CALLBACK]])</procedure>
128<procedure> (set-window-iconify-callback! [WINDOW [CALLBACK]])</procedure>
129<procedure> (set-framebuffer-size-callback! [WINDOW [CALLBACK]])</procedure>
130<procedure> (set-mouse-button-callback! [WINDOW [CALLBACK]])</procedure>
131<procedure> (set-cursor-enter-callback! [WINDOW [CALLBACK]])</procedure>
132<procedure> (set-cursor-position-callback! [WINDOW [CALLBACK]])</procedure>
133<procedure> (set-scroll-callback! [WINDOW [CALLBACK]])</procedure>
134<procedure> (set-key-callback! [WINDOW [CALLBACK]])</procedure>
135<procedure> (set-char-callback! [WINDOW [CALLBACK]])</procedure>
136<procedure> (set-char-mods-callback! [WINDOW [CALLBACK]])</procedure>
137<procedure> (set-monitor-callback! [CALLBACK])</procedure>
138<procedure> (set-joystick-callback! [CALLBACK])</procedure>
139
140Set the callback functions associated with {{WINDOW}}. Used when the callback parameters are not desired. {{WINDOW}} defaults to {{window}}. {{CALLBACK}} defaults to an external function that calls the corresponding callback parameter.
141
142
143==== Modified functions
144The following functions take a different number of arguments than their GLFW counterparts. This is because the original function accepted values passed by reference for modification.
145
146<procedure> (get-version)</procedure>
147
148Returns three values: the major version , minor version , and revision number of the GLFW library.
149
150<procedure> (get-monitors)</procedure>
151
152Returns two values: A pointer to an array of GLFWmonitor references, and the number of values in the array.
153
154<procedure> (get-monitor-position MONITOR)</procedure>
155
156Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{MONITOR}}’s viewport on the virtual screen.
157
158<procedure> (get-monitor-physical-size MONITOR)</procedure>
159
160Returns two values: the physical width and height, in millimetres, of the {{MONITOR}}.
161
162<procedure> (get-video-modes MONITOR)</procedure>
163
164Returns two values: A pointer to an array of video modes, and the number of values in the array.
165
166<procedure> (get-window-position WINDOW)</procedure>
167
168Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{WINDOW}}.
169
170<procedure> (set-window-position WINDOW X Y)</procedure>
171
172Set the position of the upper-left corner of the {{WINDOW}}.
173
174<procedure> (get-window-size WINDOW)</procedure>
175
176Returns two values: the width and height, in screen coordinates, of the {{WINDOW}}.
177
178<procedure> (get-framebuffer-size WINDOW)</procedure>
179
180Returns two values: the width and height, in pixels, of the framebuffer of {{WINDOW}}.
181
182<procedure> (get-cursor-position WINDOW)</procedure>
183
184Returns two values: the x and y position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
185
186<procedure> (set-cursor-position WINDOW X Y)</procedure>
187
188Set the position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
189
190<procedure> (get-joystick-axes JOYSTICK)</procedure>
191
192Returns two values: a pointer to an array of floats representing the values of all axes of the specified joystick, and the number of values in the array.
193
194<procedure> (get-joystick-buttons JOYSTICK)</procedure>
195
196Returns two values: a pointer to an array of bytes representing the state of all buttons on the specified joystick, and the number of values in the array.
197
198
199=== Example
200<enscript highlight="scheme">    
201(use (prefix glfw3 glfw:))
202
203(glfw:key-callback (lambda (window key scancode action mods)
204                     (cond
205                      [(and (eq? key glfw:+key-escape+) (eq? action glfw:+press+))
206                       (glfw:set-window-should-close window #t)])))
207
208(glfw:with-window (640 480 "Example" resizable: #f)
209    (let loop ()
210      (glfw:swap-buffers (glfw:window))
211      (glfw:poll-events)
212      (unless (glfw:window-should-close (glfw:window))
213        (loop))))
214</enscript>
215
216
217=== Version history
218
219==== Version 0.7.0
22015 March 2019
221
222* Maintenance given to [[/users/kooda|Kooda]]
223* Port to CHICKEN 5
224* Update to GLFW 3.2
225* Windows and OS X support has not been tested
226
227
228==== Version 0.6.1
22920 November 2014
230
231* Add OpenGL ES, Windows, and OS X support
232* Remove Scheme-settable error callback
233
234
235==== Version 0.5.2
23620 October 2014
237
238* Add {{swap-interval}} keyword to {{make-window}}
239* Add some aliases for consistency
240
241'''Version 0.5.1'''
242
24311 June 2014
244
245* Remove unintended use of miscmacros
246
247'''Version 0.5.0'''
248
24910 June 2014
250
251* Return output values passed by reference
252
253
254==== Version 0.4.1
25523 May 2014
256
257* Remove magic opengl-glew initialization (Thanks to terpri!)
258
259'''Version 0.4.0'''
260
26122 May 2014
262* Reorganize into two modules
263* Add callback functions and parameters
264* Add {{init}}
265* Add {{make-context-current}}
266* Fix a number of unsafe bindings that could potentially call back to Scheme
267
268
269==== Version 0.3.0
270* Make {{*window*}} a parameter named {{window}}
271
272
273==== Version 0.2.0
274* Add {{make-window}}, {{with-window}}
275
276
277==== Version 0.1.0
278* Initial release
279
280
281=== Source repository
282Source available [[https://www.upyum.com/cgit.cgi/glfw3-chicken/|here]].
283
284Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com
285
286
287=== Authors
288Alex Charlton
289Adrien (Kooda) Ramos
290
291
292=== Licence
293BSD
294
Note: See TracBrowser for help on using the repository browser.