source: project/wiki/eggref/4/glfw3 @ 33378

Last change on this file since 33378 was 33378, checked in by wasamasa, 3 years ago

Add a space

File size: 13.1 KB
Line 
1== glfw3
2[[toc:]]
3
4=== Description
5Bindings to the [[http://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
7This egg has been tested and /should/ work with Linux, OS X, Windows, and OpenGL ES.
8
9When using with ES, make sure GLFW is appropriately compiled (e.g.: {{cmake -DGLFW_USE_EGL=ON -DGLFW_CLIENT_LIBRARY=glesv2 -DBUILD_SHARED_LIBS=ON}}). If ES support is desired on a non-ARM platform, compile this egg with the feature {{gles}} (e.g.: {{chicken-install -D gles glfw3}}). Also, for ES, do not call {{make-window}} with {{client-api}} set, or else bad things.
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
19glf3 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 [[http://wiki.call-cc.org/eggref/4/bind|bind]]. Names have been converted from camelCase to hyphenated, with GLFW prefixes removed. Constants are surrounded by {{+}}s (e.g. {{+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 [[http://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 {{window}}.
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 [[http://www.glfw.org/docs/latest/window.html#window_hints|GLFW window hints]]. {{resizable}}, {{visible}}, {{decorated}}, {{sterio}}, {{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 [[http://www.glfw.org/faq.html#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> monitor-callback</parameter>
113
114Called 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+}}.
115
116<procedure> (set-window-position-callback! [WINDOW [CALLBACK]])</procedure>
117<procedure> (set-window-size-callback! [WINDOW [CALLBACK]])</procedure>
118<procedure> (set-window-close-callback! [WINDOW [CALLBACK]])</procedure>
119<procedure> (set-window-focus-callback! [WINDOW [CALLBACK]])</procedure>
120<procedure> (set-window-iconify-callback! [WINDOW [CALLBACK]])</procedure>
121<procedure> (set-framebuffer-size-callback! [WINDOW [CALLBACK]])</procedure>
122<procedure> (set-mouse-button-callback! [WINDOW [CALLBACK]])</procedure>
123<procedure> (set-cursor-enter-callback! [WINDOW [CALLBACK]])</procedure>
124<procedure> (set-cursor-position-callback! [WINDOW [CALLBACK]])</procedure>
125<procedure> (set-scroll-callback! [WINDOW [CALLBACK]])</procedure>
126<procedure> (set-key-callback! [WINDOW [CALLBACK]])</procedure>
127<procedure> (set-char-callback! [WINDOW [CALLBACK]])</procedure>
128<procedure> (set-monitor-callback! [WINDOW [CALLBACK]])</procedure>
129
130Set 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.
131
132
133==== Modified functions
134The 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.
135
136<procedure> (get-version)</procedure>
137
138Returns three values: the major version , minor version , and revision number of the GLFW library.
139
140<procedure> (get-monitors)</procedure>
141
142Returns two values: A pointer to an array of GLFWmonitor references, and the number of values in the array.
143
144<procedure> (get-monitor-position MONITOR)</procedure>
145
146Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{MONITOR}}’s viewport on the virtual screen.
147
148<procedure> (get-monitor-physical-size MONITOR)</procedure>
149
150Returns two values: the physical width and height, in millimetres, of the {{MONITOR}}.
151
152<procedure> (get-video-modes MONITOR)</procedure>
153
154Returns two values: A pointer to an array of video modes, and the number of values in the array.
155
156<procedure> (get-window-position WINDOW)</procedure>
157
158Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{WINDOW}}.
159
160<procedure> (set-window-position WINDOW X Y)</procedure>
161
162Set the position of the upper-left corner of the {{WINDOW}}.
163
164<procedure> (get-window-size WINDOW)</procedure>
165
166Returns two values: the width and height, in screen coordinates, of the {{WINDOW}}.
167
168<procedure> (get-framebuffer-size WINDOW)</procedure>
169
170Returns two values: the width and height, in pixels, of the framebuffer of {{WINDOW}}.
171
172<procedure> (get-cursor-position WINDOW)</procedure>
173
174Returns two values: the x and y position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
175
176<procedure> (set-cursor-position WINDOW X Y)</procedure>
177
178Set the position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
179
180<procedure> (get-joystick-axes JOYSTICK)</procedure>
181
182Returns 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.
183
184<procedure> (get-joystick-buttons JOYSTICK)</procedure>
185
186Returns 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.
187
188
189=== Example
190<enscript highlight="scheme">    
191(use (prefix glfw3 glfw:))
192
193(glfw:key-callback (lambda (window key scancode action mods)
194                     (cond
195                      [(and (eq? key glfw:+key-escape+) (eq? action glfw:+press+))
196                       (glfw:set-window-should-close window #t)])))
197
198(glfw:with-window (640 480 "Example" resizable: #f)
199    (let loop ()
200      (glfw:swap-buffers (glfw:window))
201      (glfw:poll-events)
202      (unless (glfw:window-should-close (glfw:window))
203        (loop))))
204</enscript>
205
206
207=== Version history
208
209==== Version 0.6.1
21020 November 2014
211
212* Add OpenGL ES, Windows, and OS X support
213* Remove Scheme-settable error callback
214
215
216==== Version 0.5.2
21720 October 2014
218
219* Add {{swap-interval}} keyword to {{make-window}}
220* Add some aliases for consistency
221
222'''Version 0.5.1'''
223
22411 June 2014
225
226* Remove unintended use of miscmacros
227
228'''Version 0.5.0'''
229
23010 June 2014
231
232* Return output values passed by reference
233
234
235==== Version 0.4.1
23623 May 2014
237
238* Remove magic opengl-glew initialization (Thanks to terpri!)
239
240'''Version 0.4.0'''
241
24222 May 2014
243* Reorganize into two modules
244* Add callback functions and parameters
245* Add {{init}}
246* Add {{make-context-current}}
247* Fix a number of unsafe bindings that could potentially call back to Scheme
248
249
250==== Version 0.3.0
251* Make {{*window*}} a parameter named {{window}}
252
253
254==== Version 0.2.0
255* Add {{make-window}}, {{with-window}}
256
257
258==== Version 0.1.0
259* Initial release
260
261
262=== Source repository
263Source available on [[https://github.com/AlexCharlton/glfw3-chicken|GitHub]].
264
265Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
266
267
268=== Author
269Alex Charlton
270
271
272=== Licence
273BSD
274
Note: See TracBrowser for help on using the repository browser.