-
+
- Call winwin_update once a frame in a persistent object +
- Create window(s) +
- Draw to them +
- Do input polling if desired +
+
+
+
+
+Click on sections to expand/collapse them.
Quick display controls: +Categories +· Sections +· Everything +·
+
+Getting started Basics Basicswinwin_update()
winwin_create(x, y, width, height, config)➜ winwin_destroy(window) winwin_exists(window)➜
winwin_config() winwin_config()caption: string kind: int kind: intwinwin_kind_normal winwin_kind_borderless winwin_kind_tool resize: bool show: bool topmost taskbar_button clickthrough noactivate per_pixel_alpha close_button vsync thread owner winwin_main Drawing Drawingwinwin_draw_begin(window)➜ winwin_draw_clear(color, alpha = 1) winwin_draw_sync()➜ winwin_draw_end()➜ winwin_resize_buffer(window, width, height)➜ Known issues Input InputKeyboard Keyboardwinwin_keyboard_check(window, key)➜ winwin_keyboard_check_pressed(window, key)➜ winwin_keyboard_check_released(window, key)➜ winwin_keyboard_get_string(window)➜ winwin_keyboard_set_string(window, string)➜ winwin_keyboard_get_max_string_length(window)➜ winwin_keyboard_set_max_string_length(window)➜ Mouse Mousewinwin_mouse_is_over(window)➜ winwin_mouse_get_x(window)➜int winwin_mouse_get_y(window)➜int winwin_mouse_check_button(window, button)➜ winwin_mouse_check_button_pressed(window, button)➜ winwin_mouse_check_button_released(window, button)➜ winwin_mouse_wheel_up(window)➜ winwin_mouse_wheel_down(window)➜ winwin_mouse_wheel_get_delta_x(window)➜int winwin_mouse_wheel_get_delta_y(window)➜int Gamepad Position and size Position and sizewinwin_get_x(window)➜ winwin_get_y(window)➜ winwin_get_width(window)➜ winwin_get_height(window)➜ winwin_set_position(window, x, y)➜ winwin_set_size(window, width, height)➜ winwin_set_rectangle(window, x, y, width, height)➜ window_set_min_width(window, ?min_width?)➜ window_set_min_height(window, ?min_height?)➜ window_set_max_width(window, ?max_width?)➜ window_set_max_height(window, ?max_height?)➜ window_get_min_width(window)➜ window_get_min_height(window)➜ window_get_max_width(window)➜ window_get_max_height(window)➜ Properties Propertieswinwin_set_caption(window, caption)➜ winwin_get_caption(window)➜
winwin_set_visible(window, visible)➜ winwin_get_visible(window)➜
winwin_set_owner(window, owner) winwin_get_owner(window)➜
winwin_set_taskbar_button_visible(window, show_button)➜ winwin_get_taskbar_button_visible(window)➜
winwin_set_clickthrough(window, enable_clickthrough)➜ winwin_get_clickthrough(window)➜
winwin_set_noactivate(window, disable_activation)➜ winwin_get_noactivate(window)➜
winwin_set_close_button(window, state)➜ winwin_get_close_button(window)➜
winwin_set_vsync(window, vsync)➜ winwin_get_vsync(window)➜ Z-Order Z-Orderwinwin_order_after(window, other_window)➜ winwin_order_front(window)➜ winwin_order_back(window)➜
winwin_set_topmost(window, enable)➜ winwin_get_topmost(window)➜ Focus Focuswinwin_has_focus(window)➜ winwin_get_focus()➜ winwin_set_focus(window)➜ Window shapes Window shapeswinwin_get_alpha(window)➜ winwin_set_alpha(window, alpha)➜
winwin_set_chromakey(window, color)➜ winwin_get_chromakey(window)➜int
winwin_enable_per_pixel_alpha(window)➜ winwin_enable_per_pixel_alpha(window)Premultiplied alpha Hit testing One-way ticket Cursors Cursorswinwin_set_cursor(window, cursor)➜ winwin_get_cursor(window)➜ winwin_set_cursor_handle(window, hcursor)➜ winwin_get_cursor_handle(window)➜ Working with other extensions Working with other extensionswinwin_get_handle(window)➜ winwin_from_handle(handle)➜ Other functions Other functionswinwin_sleep(milliseconds, ?process_messages)➜ winwin_game_end(exit_code = 0)➜ Known issues
+
+
+Windows' windows
This is a "cheat sheet" for "winwin" extension by YellowAfterlife. +
+The extension can be found on itch.io. +
+The source code can be found on GitHub.
+Quick display controls: +Categories +· Sections +· Everything +·
+
+ + + + + + + + + + + + + +
+ Call this once a frame! +
+ Creates a new window! +
+ xywh are in screen coordinates.
+
+ config is a winwin_config.
+
+ For example, +
+var config = new winwin_config(); +config.caption = "Hello!"; +config.resize = true; +window = winwin_create(window_get_x() - 400, window_get_y(), 350, 600, config); +
+ Destroys a previously created window. +
+ Returns whether the specified window exists. +
+ This also checks whether the passed reference is a window at all (e.g. not an undefined).
+
+ This struct holds a variety of properties that can be set when creating new windows. +
+ You can create one using new winwin_config() and fill out the desired variables.
+
+ Shown in the window's title bar, if visible. +
+ Determines window border style +
+ Just a normal window (default). +
+ A borderless window. +
+ A "tool" window with smaller borders and title bar. +
+ These can only show a close button and do not appear in taskbar. +
+ Whether the window can be resized (defaults to false).
+
+ Whether the window should be shown immediately after creation. +
+ Setting this to false can be convenient if you're going to do
+ additional setup before showing the window to the user yourself
+ (using winwin_set_visible).
+
+ Defaults to true.
+
+ Whether the window should be marked as stay-on-top. +
+ Same effect as winwin_set_topmost. +
+ Defaults to false.
+
+ Whether the window should have a taskbar shown for it. +
+ Same effect as winwin_set_taskbar_button_visible. +
+ Currently only works for borderless windows + since tool windows can't have a taskbar button + and regular windows require additional setup for this. +
+ Defaults to true.
+
+ Whether the window should be click-through. +
+ Same effect as winwin_get_clickthrough. +
+ Defaults to false.
+
+ Whether the window should not be possible to activate/focus. +
+ Same effect as winwin_set_noactivate. +
+ Defaults to false.
+
+ If true, essentially calls winwin_enable_per_pixel_alpha upon creating the window.
+
+ Defaults to false.
+
+ Whether the window's close button should be enabled and what it should do. +
+ Same effect as winwin_set_close_button. +
+ Defaults to 1.
+
+ Indicates the window's vertical synchronization state. +
+ Same effect as winwin_set_vsync. +
+ Defaults to 0.
+
+ Whether the window should do its message handling on a different thread. +
+ This takes marginally more resources and might have situational implications + (because the window is no longer owned by the thread where your game code and extensions run), + but this prevents the game window from freezing while the additional windows are being dragged around. +
+ It is not possible to make winwin_main threaded, + but you could use Gameframe + or hide your main window and draw the game to another one. +
+ Defaults to false.
+
+ If set, equivalent to winwin_set_owner. +
+ Defaults to undefined.
+
+ This is a reference to your main game window. +
+ It enables using a handful of extension functions on it, with some remarks:
-
+
- Input functions just call the respective GM functions + since GM is responsible for input handling on the game window. +
- Drawing functions (like winwin_draw_begin) don't really work + and don't have to be used either. +
- Cursor functions don't work, but you can use the built-in functions + (and/or Native Cursors). +
+ Starts drawing to the specified window. +
+ By most means this is like surface_set_target, but for windows. +
+ Returns whether successful. + Can fail if you're already drawing to another window. +
+ The built-in draw_clear and draw_clear_alpha functions cannot draw to additional
+ windows because they respect the game's original drawing bounds,
+ so I'm giving you this helper function for clearing the window to whatever color and opacity.
+
+ If you're doing a surface_set_target while drawing to an additional window,
+ call this after surface_reset_target to make GM draw to that window window again
+ (otherwise the subsequent drawing operations will end up in the main window instead).
+
+ Returns whether successful. + Returns false if you're not drawing to a window. +
+ Stops drawing to the specified window and updates its contents. +
+ This happens immediately and can be used to display debug information + in additional windows while the game is busy (e.g. generating a level). +
+ Returns whether successful. + Returns false if you're not drawing to a window. +
+ A typical use of drawing functions might look as following: +
+winwin_draw_begin(my_window); +winwin_draw_clear(c_white); +draw_set_color(c_black); +draw_text(5, 5, "Hello!"); +winwin_draw_end(); +
+ Changes internal drawing buffer size of a window. +
+ You shouldn't have to call this explicitly since it'll be called for you a few frames + after a window's size changes. +
+ Returns whether successful. +
+ I do not go through the trouble of completely clearing-restoring the drawing state, + so there are occasional opportunities for self-sabotage if you are setting your own + matrices / clip rectangles / etc. +
+ To be fair, you could just use keyboard_check_direct as a replacement for most of these, but where's the fun in that? +
+ Text entry: +
+ Like keyboard_string, but for additional windows.
+
+ The behaviour should generally be identical to how the built-in variable works, but without erasing it when the window loses focus (why's that a thing, anyway?). +
+ Changes the current keyboard string for a window. +
+ Settings: +
+ Returns how long a keyboard_string of the given window is allowed to get, in characters.
+
+ Default is 128. +
+ Changes how long a keyboard_string of the given window is allowed to get, in characters.
+
+ Returns whether successful. +
+ Returns whether the cursor is currently over the given window. +
+ Like window_mouse_get_x, but for additional windows.
+
+ Like window_mouse_get_y, but for additional windows.
+
+ Buttons: +
+ Wheel: +
+ Returns horizontal wheel delta since last frame. +
+ Per Microsoft documentation, 120 units should be equivalent to one wheel tick. +
+ Returns vertical wheel delta since last frame. +
+ Per Microsoft documentation, 120 units should be equivalent to one wheel tick. +
+ Doing gamepad polling for each window would be both high-effort and computationally taxing, + but you can use extensions to poll gamepad input regardless of what window has focus + (XInput, + DirectInput) +
+ These return the current position/size of a window.
+ They'll return undefined if the window has been closed or cannot be measured.
+
+ These change position/size of a window: +
+ These let you change min/max size of a window.
+ Pass undefined instead of a size to not restrict:
+
+ These return min/max size of a window (or undefined if not set):
+
+ Changes the caption/title of a window, like window_set_caption.
+
+ Returns whether successful. +
+ Returns the caption/title of a window. +
+ Shows/hides a window. +
+ Returns whether successful. +
+ Returns whether a window is visible. +
+ Changes the window owner (GWLP_HWNDPARENT).
+
+ Linked windows always appear over the owner window, + minimize along with it, and are generally what you want + for any pop-out panels and alike. +
+ owner can be undefined to un-link.
+
+ Returns the current window owner
+ (or undefined if not linked).
+
+ Changes whether the taskbar button is visible. +
+ Currently only works for borderless windows (see winwin_config.taskbar_button). +
+ Returns whether successful. +
+ Returns whether a window's taskbar button is visible. +
+ Changes whether a window is click-through. +
+ Click-through windows let through all mouse events - good for overlays + or making some portions of the window + (e.g. ones with per-pixel transparency) non-interactive. +
+ Returns whether successful. +
+ Returns whether a window is click-through. +
+ Returns whether the window should have activation disabled. +
+ This prevents giving it focus in most usual means. +
+ Returns whether successful. +
+ Returns whether a window has activation disabled. +
+ Changes a window's close button state. Allowed values are:
-
+
-
0(orfalse): close button is visibly disabled + -
1(ortrue): close button is enabled;
+ Closing the window destroys it, which you can check for using winwin_exists. + -
2: close button is enabled;
+ Closing the window hides it (as with winwin_set_visible), + which you can check for using winwin_get_visible. +
+ Returns whether successful. +
+ Returns a window's close button state. +
+ Changes whether drawing to a specific window uses vertical synchronization. +
+ Using values larger than 1 will draw every N-th blank.
+
+ The intricacies of using vsync across multiple windows of the same application + have not been extensively studied. +
+ Returns the window's vertical synchronization value. +
+ Puts the window in front of another window. +
+ Returns whether successful. +
+ Moves the window to the front (like when giving it focus). +
+ Returns whether successful. +
+ Moves the window to the back. +
+ Returns whether successful. +
+ Changes whether the window should be stay-on-top. +
+ Returns whether successful. +
+ Returns whether the window is stay-on-top. +
+ Like window_has_focus, but for additional windows.
+
+ Returns the window that currently has keyboard focus,
+ or undefined if there's none or it's not part of the current application.
+
hscript error!
+{ fileName => hscript, lineNumber => 9 } hscript:9: Invalid number of parameters. Got 1, required 2 for function 'msdn'
+Called from hscript/Interp.hx line 415
+Called from a C function
+Called from hscript/Interp.hx line 684
+Called from hscript/Interp.hx line 381
+Called from hscript/Interp.hx line 259
+Called from hscript/Interp.hx line 258
+Called from hscript/Interp.hx line 254
+Called from dmd/tags/TagExec.hx line 76+ Forces keyboard focus upon a window. +
+ Returns whether successful. +
+ Consider these a trimmed-down version of + window_shape. +
+ Returns opacity of a window in 0..1 range. +
+ Changes opacity of a window (alpha being a 0..1 range). +
+ Returns whether successful. +
+ Changes the chromakey color for a window. +
+ Pixels that fully match this color will be see-through and click-through. +
+ Pass -1 instead of the color to disable chromakey.
+
+ Returns the window's chromakey color (-1 if disabled).
+
+ Quoting my own notes from window_shape, +
+ This function calls + DwmEnableBlurBehindWindow + for a zero-sized region. +
+ Doing so also happens to enable partial transparency support for the contents of the window + ("The alpha values in the window are honored"). +
+ For example, if you did +
+draw_clear_alpha(c_black, 0); +
+ in a Draw event of the only instance in a room, your window would look like an empty frame. +
+ For a proper setup, make sure that
+ "Clear Display Buffer",
+ "Enable Viewports" (with at least one view set up),
+ and "Clear Viewport Background"
+ are enabled for the room;
+ see desktop_friend project for a slightly more sophisticated example.
+
+ Now let's talk about the conditions and caveats: +
+ Windows expects the window pixels to have premultiplied alpha. +
+ In short, instead of just color, the pixels should be colored with
+
+merge_color(c_black, color, alpha) +
+ For sprites, all recent GameMaker versions have a "Premultiply alpha" checkbox + in the Texture Settings; +
+ For text and primitives, you'll need to use the above formula; +
+ For mixing multiple semi-transparent images together, see the classic + GameMaker surface problems and solutions. +
+ If you don't use pre-multiplied alpha, your window will still work, + but the semi-transparent bright portions will appear lighter than they should be. +
+ According to Windows, just because a pixel is now almost or completely transparent, + that doesn't mean that you can't click it! +
+ You can use the extension's other functions (be it shapes or chromakey)
+ to narrow down the window's shape, or use the
+ winwin_set_clickthrough function
+ to make the window clickable/un-clickable
+ based on where the cursor is.
+
+ The function has been around since Windows 7,
+ yet it doesn't seem like you can go back to an opaque window
+ once you have called it - even if you pass dwFlags of 0.
+
+ You can "top-up" the opacity of the window contents by drawing a black rectangle
+ with bm_add blend mode or any rectangle with gpu_set_colourwriteenable
+ (or draw_set_colour_write_enable for GMS1) of (0, 0, 0, 1).
+
+ Changes the window's current cursor, using GameMaker cr_ constants.
+
+ You can also use -18 (cr_no from GM8) for a 🚫 cursor.
+
+ Returns whether successful. +
+ Returns which cursor (out of the built-in set) the window is currently using. +
+ If it's not using any of those, returns undefined.
+
+ Custom cursors: +
+ Changes the window's current cursor to a new HCURSOR (ptr).
+
+ You can only get these from other extensions. +
+ Returns the window's current cursor as HCURSOR.
+
+ Make sure to not accidentally delete winwin's cursors as these are shared + between all windows. +
+ Returns a WinAPI window handle for the given window,
+ just like the built-in window_handle function does.
+
+ Converts a WinAPI window handle back to a window reference. +
+ If there's no known window with that handle, returns undefined.
+
+ A native sleep function that pauses the game for a number of milliseconds. +
+ If process_messages is true (or not provided),
+ does message handling every 100ms and after the wait so that Windows
+ doesn't start showing your game window as "not responding".
+
+ MSDN: Sleep +
+ Calls a C exit function that kills your process on spot. No further code will execute.
+
-
+
If the user has set up a custom Max Frame Rate override in NVIDIA Control Panel, + the limit works as (value / active window count) instead. +
+ The underlying cause seems to be that NVIDIA driver counts
Presentcalls + on per-process basis rather than per-window. ++ I haven't come up with a Cool Workaround for this yet, + but if the user has set up it themselves, they can also remove the override. +
Drawing with shaders into additional windows works weird. +
+ Probably changes some D3D11 state that I'm not aware of. +
+ For now, you can draw things with shaders onto a surface and then draw that surface + into a window. +