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

Last change on this file since 30909 was 30909, checked in by acharlton, 6 years ago

Update to version 0.4.1

File size: 9.8 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
7
8=== Requirements
9* Bind
10
11
12=== Documentation
13glf3 is separated into two modules: {{glfw3-bindingw}} and {{glfw3}}. For almost all purposes, only {{glfw3}} should be needed.
14
15{{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+}}).
16
17{{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]].
18
19For information regarding the GLFW API, see the official [[http://www.glfw.org/documentation.html|GLFW documentation]].
20
21
22==== High-level interface
23<procedure> (init)</procedure>
24
25Initializes glfw, as well as {{error-callback}} and {{monitor-callback}}. Not needed when using {{with-window}}.
26
27<parameter> window</parameter>
28
29Contains the window associated with the current context.
30
31<procedure> (make-context-current WINDOW)</procedure>
32
33Performs {{glfwMakeContextCurrent}} while setting {{window}}.
34
35<procedure> (make-window WIDTH HEIGHT NAME #!key (fullscreen? #f) 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>
36
37Create 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.
38
39Sets the current context to the window that was created. Also sets the swap interval of the window to {{1}}, for convenience. This can be later set by {{swap-interval}}. Finally, this initializes all of the window-specific callbacks.
40
41<macro> (with-window (WIDTH HEIGHT NAME . KEYS) BODY ...)</macro>
42
43Initializes GLFW, creates a window as per {{make-window}}, and runs {{BODY}} before cleaning up.
44
45
46==== Callbacks
47{{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.
48
49<parameter> error-callback</parameter>
50
51Called when a GLFW error occurs. Expects a function with the signature {{(lambda (CODE MESSAGE) ...)}}. {{CODE}} is one of {{+not-initialized+}}, {{+no-current-context+}}, {{+invalid-enum+}}, {{+invalid-value+}}, {{+out-of-memory+}}, {{+api-unavailable+}}, {{+version-unavailable+}}, {{+platform-error+}}, {{+format-unavailable+}}. {{MESSAGE}} is a string containing an error message.
52
53Defaults to a function that throws an error and prints {{MESSAGE}}.
54
55<parameter> window-position-callback</parameter>
56
57Called 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.
58
59<parameter> window-size-callback</parameter>
60
61Called 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.
62
63<parameter> window-close-callback</parameter>
64
65Called when a window is closed. Expects a function with the signature {{(lambda (WINDOW) ...)}}. {{WINDOW}} is the window that was closed.
66
67<parameter> window-focus-callback</parameter>
68
69Called 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.
70
71<parameter> window-iconify-callback</parameter>
72
73Called 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.
74
75<parameter> framebuffer-size-callback</parameter>
76
77Called 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.
78
79<parameter> mouse-button-callback</parameter>
80
81Called 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+}}).
82
83<parameter> cursor-enter-callback</parameter>
84
85Called 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.
86
87<parameter> cursor-position-callback</parameter>
88
89Called 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.
90
91<parameter> scroll-callback</parameter>
92
93Called 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.
94
95<parameter> key-callback</parameter>
96
97Called 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+}}).
98
99<parameter> char-callback</parameter>
100
101Called 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.
102
103<parameter> monitor-callback</parameter>
104
105Called 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+}}.
106
107<procedure> (set-error-callback! [WINDOW [CALLBACK]])</procedure>
108<procedure> (set-window-position-callback! [WINDOW [CALLBACK]])</procedure>
109<procedure> (set-window-size-callback! [WINDOW [CALLBACK]])</procedure>
110<procedure> (set-window-close-callback! [WINDOW [CALLBACK]])</procedure>
111<procedure> (set-window-focus-callback! [WINDOW [CALLBACK]])</procedure>
112<procedure> (set-window-iconify-callback! [WINDOW [CALLBACK]])</procedure>
113<procedure> (set-framebuffer-size-callback! [WINDOW [CALLBACK]])</procedure>
114<procedure> (set-mouse-button-callback! [WINDOW [CALLBACK]])</procedure>
115<procedure> (set-cursor-enter-callback! [WINDOW [CALLBACK]])</procedure>
116<procedure> (set-cursor-position-callback! [WINDOW [CALLBACK]])</procedure>
117<procedure> (set-scroll-callback! [WINDOW [CALLBACK]])</procedure>
118<procedure> (set-key-callback! [WINDOW [CALLBACK]])</procedure>
119<procedure> (set-char-callback! [WINDOW [CALLBACK]])</procedure>
120<procedure> (set-monitor-callback! [WINDOW [CALLBACK]])</procedure>
121
122Set the callback functions associated with {{WINDOW}}. {{WINDOW}} defaults to {{window}}. {{CALLBACK}} defaults to an external function that calls the corresponding callback parameter.
123
124
125=== Example
126<enscript highlight="scheme">    
127(use (prefix glfw3 glfw:))
128
129(glfw:key-callback (lambda (window key scancode action mods)
130                     (cond
131                      [(and (eq? key glfw:+key-escape+) (eq? action glfw:+press+))
132                       (glfw:set-window-should-close window #t)])))
133
134(glfw:with-window (640 480 "Example" resizable: #f)
135    (let loop ()
136      (glfw:swap-buffers (glfw:window))
137      (glfw:poll-events)
138      (unless (glfw:window-should-close (glfw:window))
139        (loop))))
140</enscript>
141
142
143=== Version history
144
145==== Version 0.4.1
146* Remove magic opengl-glew initialization (Thanks to terpri!)
147
148'''Version 0.4.0'''
149
150* Reorganize into two modules
151* Add callback functions and parameters
152* Add {{init}}
153* Add {{make-context-current}}
154* Fix a number of unsafe bindings that could potentially call back to Scheme
155
156
157==== Version 0.3.0
158* Make {{*window*}} a parameter named {{window}}
159
160
161==== Version 0.2.0
162* Add {{make-window}}, {{with-window}}
163
164
165==== Version 0.1.0
166* Initial release
167
168
169=== Source repository
170Source available on [[https://github.com/AlexCharlton/glfw3-chicken|GitHub]].
171
172Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
173
174
175=== Author
176Alex Charlton
177
178
179=== Licence
180BSD
181
Note: See TracBrowser for help on using the repository browser.