Changeset 37739 in project


Ignore:
Timestamp:
06/25/19 17:40:14 (3 weeks ago)
Author:
kooda
Message:

Update docs for glfw3 0.7.1

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/glfw3

    r37398 r37739  
     1
    12== glfw3
    23[[toc:]]
     
    2728
    2829==== High-level interface
    29 <procedure> (init)</procedure>
     30<procedure>(init)</procedure>
    3031
    3132Initializes glfw. Not needed when using {{with-window}}.
    3233
    33 <parameter> window</parameter>
     34<parameter>window</parameter>
    3435
    3536Contains the window associated with the current context.
    3637
    37 <procedure> (make-context-current WINDOW)</procedure>
     38<procedure>(make-context-current WINDOW)</procedure>
    3839
    3940Performs {{glfwMakeContextCurrent}} while setting the above {{window}} parameter to the new value.
    4041
    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<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>
    4243
    4344Create 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.
     
    4748When 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:
    4849
    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>
     50 (make-window WIDTH HEIGHT NAME
     51              context-version-major: 3
     52              context-version-minor: 2
     53              opengl-forward-compat: #t
     54              opengl-profile: +opengl-core-profile+)
     55 
     56 
     57<macro>(with-window (WIDTH HEIGHT NAME . KEYS) BODY ...)</macro>
    5758
    5859Initializes GLFW, creates a window as per {{make-window}}, and runs {{BODY}} before cleaning up.
     
    6263{{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.
    6364
    64 <parameter> window-position-callback</parameter>
     65<parameter>window-position-callback</parameter>
    6566
    6667Called 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.
    6768
    68 <parameter> window-size-callback</parameter>
     69<parameter>window-size-callback</parameter>
    6970
    7071Called 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.
    7172
    72 <parameter> window-close-callback</parameter>
     73<parameter>window-close-callback</parameter>
    7374
    7475Called when a window is closed. Expects a function with the signature {{(lambda (WINDOW) ...)}}. {{WINDOW}} is the window that was closed.
    7576
    76 <parameter> window-focus-callback</parameter>
     77<parameter>window-refresh-callback</parameter>
     78
     79Called when a window’s content is damaged and needs to be refreshed. Expects a function with the signature {{(lambda (WINDOW) ...)}}. {{WINDOW}} is the window that needs refreshing.
     80
     81<parameter>window-focus-callback</parameter>
    7782
    7883Called 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.
    7984
    80 <parameter> window-iconify-callback</parameter>
     85<parameter>window-iconify-callback</parameter>
    8186
    8287Called 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.
    8388
    84 <parameter> framebuffer-size-callback</parameter>
     89<parameter>framebuffer-size-callback</parameter>
    8590
    8691Called 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.
    8792
    88 <parameter> mouse-button-callback</parameter>
     93<parameter>mouse-button-callback</parameter>
    8994
    9095Called 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+}}).
    9196
    92 <parameter> cursor-enter-callback</parameter>
     97<parameter>cursor-enter-callback</parameter>
    9398
    9499Called 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.
    95100
    96 <parameter> cursor-position-callback</parameter>
     101<parameter>cursor-position-callback</parameter>
    97102
    98103Called 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.
    99104
    100 <parameter> scroll-callback</parameter>
     105<parameter>scroll-callback</parameter>
    101106
    102107Called 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.
    103108
    104 <parameter> key-callback</parameter>
     109<parameter>key-callback</parameter>
    105110
    106111Called 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+}}).
    107112
    108 <parameter> char-callback</parameter>
     113<parameter>char-callback</parameter>
    109114
    110115Called 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.
    111116
    112 <parameter> char-mods-callback</parameter>
     117<parameter>char-mods-callback</parameter>
    113118
    114119Called 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.
    115120
    116 <parameter> monitor-callback</parameter>
     121<parameter>monitor-callback</parameter>
    117122
    118123Called 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+}}.
    119124
    120 <parameter> joystick-callback</parameter>
     125<parameter>joystick-callback</parameter>
    121126
    122127Called 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+}}.
    123128
    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>
     129<procedure>(set-window-position-callback! [WINDOW [CALLBACK]])</procedure>
     130<procedure>(set-window-size-callback! [WINDOW [CALLBACK]])</procedure>
     131<procedure>(set-window-close-callback! [WINDOW [CALLBACK]])</procedure>
     132<procedure>(set-window-refresh-callback! [WINDOW [CALLBACK]])</procedure>
     133<procedure>(set-window-focus-callback! [WINDOW [CALLBACK]])</procedure>
     134<procedure>(set-window-iconify-callback! [WINDOW [CALLBACK]])</procedure>
     135<procedure>(set-framebuffer-size-callback! [WINDOW [CALLBACK]])</procedure>
     136<procedure>(set-mouse-button-callback! [WINDOW [CALLBACK]])</procedure>
     137<procedure>(set-cursor-enter-callback! [WINDOW [CALLBACK]])</procedure>
     138<procedure>(set-cursor-position-callback! [WINDOW [CALLBACK]])</procedure>
     139<procedure>(set-scroll-callback! [WINDOW [CALLBACK]])</procedure>
     140<procedure>(set-key-callback! [WINDOW [CALLBACK]])</procedure>
     141<procedure>(set-char-callback! [WINDOW [CALLBACK]])</procedure>
     142<procedure>(set-char-mods-callback! [WINDOW [CALLBACK]])</procedure>
     143<procedure>(set-monitor-callback! [CALLBACK])</procedure>
     144<procedure>(set-joystick-callback! [CALLBACK])</procedure>
    139145
    140146Set 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.
     
    144150The 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.
    145151
    146 <procedure> (get-version)</procedure>
     152<procedure>(get-version)</procedure>
    147153
    148154Returns three values: the major version , minor version , and revision number of the GLFW library.
    149155
    150 <procedure> (get-monitors)</procedure>
     156<procedure>(get-monitors)</procedure>
    151157
    152158Returns two values: A pointer to an array of GLFWmonitor references, and the number of values in the array.
    153159
    154 <procedure> (get-monitor-position MONITOR)</procedure>
     160<procedure>(get-monitor-position MONITOR)</procedure>
    155161
    156162Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{MONITOR}}’s viewport on the virtual screen.
    157163
    158 <procedure> (get-monitor-physical-size MONITOR)</procedure>
     164<procedure>(get-monitor-physical-size MONITOR)</procedure>
    159165
    160166Returns two values: the physical width and height, in millimetres, of the {{MONITOR}}.
    161167
    162 <procedure> (get-video-modes MONITOR)</procedure>
     168<procedure>(get-video-modes MONITOR)</procedure>
    163169
    164170Returns two values: A pointer to an array of video modes, and the number of values in the array.
    165171
    166 <procedure> (get-window-position WINDOW)</procedure>
     172<procedure>(get-window-position WINDOW)</procedure>
    167173
    168174Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the {{WINDOW}}.
    169175
    170 <procedure> (set-window-position WINDOW X Y)</procedure>
     176<procedure>(set-window-position WINDOW X Y)</procedure>
    171177
    172178Set the position of the upper-left corner of the {{WINDOW}}.
    173179
    174 <procedure> (get-window-size WINDOW)</procedure>
     180<procedure>(get-window-size WINDOW)</procedure>
    175181
    176182Returns two values: the width and height, in screen coordinates, of the {{WINDOW}}.
    177183
    178 <procedure> (get-framebuffer-size WINDOW)</procedure>
     184<procedure>(get-framebuffer-size WINDOW)</procedure>
    179185
    180186Returns two values: the width and height, in pixels, of the framebuffer of {{WINDOW}}.
    181187
    182 <procedure> (get-cursor-position WINDOW)</procedure>
     188<procedure>(get-cursor-position WINDOW)</procedure>
    183189
    184190Returns two values: the x and y position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
    185191
    186 <procedure> (set-cursor-position WINDOW X Y)</procedure>
     192<procedure>(set-cursor-position WINDOW X Y)</procedure>
    187193
    188194Set the position of the cursor, relative to the upper-left edge of the client area of the {{WINDOW}}.
    189195
    190 <procedure> (get-joystick-axes JOYSTICK)</procedure>
     196<procedure>(get-joystick-axes JOYSTICK)</procedure>
    191197
    192198Returns 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.
    193199
    194 <procedure> (get-joystick-buttons JOYSTICK)</procedure>
     200<procedure>(get-joystick-buttons JOYSTICK)</procedure>
    195201
    196202Returns 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.
     
    198204
    199205=== Example
    200 <enscript highlight="scheme">    
     206<enscript highlight="scheme">
    201207(import (prefix glfw3 glfw:))
    202208
     
    217223=== Version history
    218224
     225==== Version 0.7.1
     22625 June 2019
     227
     228* Add the missing window refresh callback
     229
     230
    219231==== Version 0.7.0
    22023215 March 2019
Note: See TracChangeset for help on using the changeset viewer.