FSAL Version 0.09

Overview

FSAL is "Full Screen Assistant for LÖVE".

FSAL provides a function to easily handle full screen mode when creating games with the LÖVE framework.

• LÖVE: https://love2d.org/

With FSAL you can easily implement full screen mode in your own games.

You will also be able to easily implement the ability to switch between full screen mode and window mode.

How to use

1. Download source from repository. (https://fsal.sourceforge.io)
2. Unpack it and put 'fullscreen.lua' in your lib folder.
3. require("fullscreen").

Functions

fsal_initialize(width, height, onoff, hidemc, grab)

Initialize FSAL

• width : Horizontal size of canvas (px)
• height: Vertical size of canvas (px)
• onoff : Full screen flag
  • true : fullscreen
  • false: windowed
• hidemc: Whether or not the mouse cursor is displayed.
  • true : show mouse cursor
  • false: hide mouse cursor
• grab : Mouse grab flag
  • true : grab mouse cursor
  • false: free mouse cursor

fsal_modechange(hidemc, grab)

Switch between full screen mode and window mode

• hidemc: Whether or not the mouse cursor is displayed in full screen.
  • true : show mouse cursor
  • false: hide mouse cursor
• grab : Mouse grab flag
  • true : grab mouse cursor
  • false: free mouse cursor

fsal_canvas()

Prepare the drawing canvas

fsal_drawstart(canvas)

Start drawing

• canvas: Target canvas (usually prepared with fsal_canvas)

fsal_drawend()

Ends drawing

fsal_show(canvas)

Display the drawn contents on the screen

• canvas: Target canvas (usually prepared with fsal_canvas)

fsal_drawbgimage(image, quad, iw, ih)

Draw an image on the background visible outside the main screen.
Use before fsal_drawstart(canvas).

• image: Image object to draw in the background
• quad : Giving a Quad here allows for background animation, etc.
• iw : When quad is given, specify the width of one frame.
• ih : When quad is given, specify the height of one frame.

fsal_simpleinit()

Initialize FSAL with the current window width and height.
The startup state is fixed to window mode.

fsal_begindraw()

Prepare a canvas for FSAL and start drawing on it.

fsal_showcanvas()

Finish drawing on the canvas for FSAL, and display what you have drawn on the fore screen.

fsal_simplechange(key, cur)

When the F11 key is pressed, it toggles between windowed and full screen mode.
Call this in love.keypressed(key) and pass key directly to this function.

• key: Parameter "key" at love.keypressed(key).
• cur: Whether or not the mouse cursor is displayed.
  • true : show mouse cursor
  • false: hide mouse cursor

fsal_getmargininfo()

If you want to draw outside the game screen area in full screen mode,
you can call this function to get the current screen coordinates.

• return value: Information of two areas as a table. {<area1>, <area2>}
  Each area infomation is as {type: Area type, x: Leftmost coordinate,
  y: Topmost coordinate, width: Area width, height: Area height}
  • Area type: "L":Left side, "R": Right side, "T": Top side, "B": Bottom side
  </area2></area1>

fsal_getscmode()

Calling this function returns whether the screen is currently full screen or not.

• return value: Information on whether or not fullscreen mode
  • true : full screen mode
  • false: window mode

fsal_convertRV(x, y)

Convert the actual coordinates to virtual coordinates of the resolution set by the game.

• return value: Adjusted Coordinates
  • tx: X coordinate after conversion
  • ty: Y coordinate after conversion

fsal_convertVR(x, y)

Convert the virtual coordinates of the resolution set by the game to actual coordinates.

• return value: Adjusted Coordinates
  • tx: X coordinate after conversion
  • ty: Y coordinate after conversion

fsal_getscale()

Obtain the magnification rate at the time of the call.

• return value: rate of magnification

fsal_resize(width, height)

Change the FSAL calculation screen size.
Must be called passing w=width and h=height from love.resize(w, h).

• width : Horizontal size of window (px)
• height: Vertical size of window (px)

fsal_resetwinsize()

Reset the window size to the FSAL canvas size.

fsal_setclipmouse(onoff, grab)

Toggles whether or not the mouse cursor is clipped within the game area.

• onoff: Game area mode flag
  • true: trap mouse cursor in game area
  • false: free mouse cursor from game area
• grab : Mouse grab flag
  • true: grab mouse cursor in window
  • false: free mouse cursor from window

fsal_clipmouse(x, y)

Adjusts the coordinates of the mouse cursor within the game area.
x, y can be given as the mouse coordinates from which the calculation is made.
If x and y are not given, the mouse coordinates are obtained and calculated.
The mouse cursor automatically moves to the correction position.
If you simply want the coordinates, use getvirtualmouse(x, y) instead.
It is unstable when used in LÖVE mouse-related callbacks.
Use getvirtualmouse(x, y) in mouse-related callbacks.

• x: X-coordinate from which to calculate
• y: Y-coordinate from which to calculate
• return value: Coordinates after conversion
  • tx: X coordinate after conversion
  • ty: Y coordinate after conversion

fsal_getvirtualmouse(x, y)

Get mouse coordinates corrected to the game canvas size.

• x: X-coordinate from which to calculate
• y: Y-coordinate from which to calculate
• return value: Coordinates after conversion
  • tx: X coordinate after conversion
  • ty: Y coordinate after conversion

Sample code

require("fullscreen")

function love.load()
  fsal_initialize(800, 600, false)
  canvas = fsal_canvas()
  bg = love.graphics.newImage("bg.jpg")
end

function love.draw()
  fsal_drawbgimage(bg)
  fsal_drawstart(canvas)
  <draw anything here>
  fsal_drawend()
  fsal_show(canvas)
end

function love.keypressed(key)
  if key == "f11" then
    fsal_modechange()
  end
end

Sample code of Simple mode

require("fullscreen")

function love.load()
  fsal_simpleinit()
end

function love.draw()
  fsal_begindraw()
  <draw anything here>
  fsal_showcanvas()
end

function love.keypressed(key)
  fsal_simplechange(key)
end

Version History

0.01 (2020/12/21):

• Initial release

0.02 (2020/12/25):

• fsal_drawbgimage added

0.03 (2022/03/21):

• Simple mode functions added

0.04 (2022/10/11):

• Vertical screen supported
• Transparent color supported

0.05 (2022/11/07):

• Background animation supported
• fsal_getmargininfo added

0.06 (2022/11/08):

• fsal_getmargininfo Improved
• fsal_getscmode added

0.07 (2022/11/29):

• Added hiding cursor option
• Changed scale to own logic

0.08 (2022/12/22):

• Changed to MOUSEY License
• fsal_convertRV/VR added
• fsal_getscale added

0.09 (2024/04/20):

• Freely resizable window supported
• Transrated coordinates supported
• fsal_resize added
• fsal_resetwinsize added
• fsal_setclipmouse added
• fsal_clipmouse added
• fsal_getvirtualmouse added

License

Copyright (C) 2020-2024 michyo (Michiyo Tagami) [https://michyo.net/]

Released under the MOUSEY license

See the LICENSE.txt for more details.

This license is almost identical to the MIT license.
The only difference is that I love mice very much.
There is no inconvenience for you that differs from an MIT license.
Please read LICENSE.txt for more information.