Difference between revisions of "love.window.setMode"

m (Added note about auto-resizing when the size isn't supported in fullscreen)
m (change dash '-' to ':' in vsync param to remove any confusion)
(32 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
{{newin|[[0.9.0]]|090|type=function|text=Moved from [[love.graphics.setMode]]}}
 
{{newin|[[0.9.0]]|090|type=function|text=Moved from [[love.graphics.setMode]]}}
  
−
Changes the display mode.
+
Sets the display mode and properties of the window.
  
 
If width or height is 0, setMode will use the width and height of the desktop.  
 
If width or height is 0, setMode will use the width and height of the desktop.  
  
−
Changing the display mode may have side effects: for example, [[canvas]]es will be cleared; make sure to save their contents beforehand if you need to.
+
Changing the display mode may have side effects: for example, [[Canvas|canvases]] will be cleared and values sent to shaders with [[Shader:send]] will be erased. Make sure to save the contents of [[Canvas|canvases]] beforehand or re-draw to them afterward if you need to.
 
== Function ==
 
== Function ==
 
=== Synopsis ===
 
=== Synopsis ===
Line 16: Line 16:
 
{{param|table|flags|The flags table with the options:}}
 
{{param|table|flags|The flags table with the options:}}
 
{{subparam|boolean|fullscreen (false)|Fullscreen (true), or windowed (false).}}
 
{{subparam|boolean|fullscreen (false)|Fullscreen (true), or windowed (false).}}
−
{{subparam|FullscreenType|fullscreentype ("normal")|The type of fullscreen to use.}}
+
{{subparam|FullscreenType|fullscreentype ("desktop")|The type of fullscreen to use. This defaults to "normal" in [[0.9.0]] through [[0.9.2]] and to "desktop" in [[0.10.0]] and older.}}
−
{{subparam|boolean|vsync (true)|True if LÖVE should wait for vsync, false otherwise.}}
+
{{subparam|number|vsync (1)|Enables or disables vertical synchronisation ('vsync'): '''1''' to enable vsync, '''0''' to disable it, and '''-1''' to use adaptive vsync (where supported). Prior to [[11.0]] this was a boolean flag, rather than a number.}}
−
{{subparam|number|fsaa (0)|The number of antialiasing samples.}}
+
{{subparam|number|msaa (0)|The number of antialiasing samples.}}
 +
{{subparam|boolean|stencil (true)|Whether a stencil buffer should be allocated. If true, the stencil buffer will have 8 bits.}}
 +
{{subparam|number|depth (0)|The number of bits in the depth buffer.}}
 
{{subparam|boolean|resizable (false)|True if the window should be resizable in windowed mode, false otherwise.}}
 
{{subparam|boolean|resizable (false)|True if the window should be resizable in windowed mode, false otherwise.}}
 
{{subparam|boolean|borderless (false)|True if the window should be borderless in windowed mode, false otherwise.}}
 
{{subparam|boolean|borderless (false)|True if the window should be borderless in windowed mode, false otherwise.}}
 
{{subparam|boolean|centered (true)|True if the window should be centered in windowed mode, false otherwise.}}
 
{{subparam|boolean|centered (true)|True if the window should be centered in windowed mode, false otherwise.}}
 
{{subparam|number|display (1)|The index of the display to show the window in, if multiple monitors are available.}}
 
{{subparam|number|display (1)|The index of the display to show the window in, if multiple monitors are available.}}
−
{{subparam|number|minwidth (100)|The minimum width of the window, if it's resizable.}}
+
{{subparam|number|minwidth (1)|The minimum width of the window, if it's resizable. Cannot be less than 1.}}
−
{{subparam|number|minheight (100)|The minimum height of the window, if it's resizable.}}
+
{{subparam|number|minheight (1)|The minimum height of the window, if it's resizable. Cannot be less than 1.}}
 +
{{New feature|0.9.1|
 +
{{subparam|boolean|highdpi (false)|True if [[love.window.getDPIScale|high-dpi mode]] should be used on Retina displays in macOS and iOS. Does nothing on non-Retina displays. This is always enabled on Android.}} }}
 +
{{New feature|0.9.2|
 +
{{subparam|number|x (nil)|The x-coordinate of the window's position in the specified display.}}
 +
{{subparam|number|y (nil)|The y-coordinate of the window's position in the specified display.}} }}
 +
{{New feature|11.3|
 +
{{subparam|boolean|usedpiscale (true)|Disables LOVE's automatic DPI scaling on high-DPI displays when false. This only has an effect when the <code>highdpi</code> flag is set to true, since the OS (rather than LOVE) takes care of everything otherwise.}} }}
 +
{{Removed new feature|0.9.1|0.10.0|
 +
{{subparam|boolean|srgb (false)|Removed in [[0.10.0]] (set t.gammacorrect in [[conf.lua]] instead). True if sRGB gamma correction should be applied when drawing to the screen.}} }}
 +
 
 
=== Returns ===
 
=== Returns ===
 
{{param|boolean|success|True if successful, false otherwise.}}
 
{{param|boolean|success|True if successful, false otherwise.}}
  
 
== Notes ==
 
== Notes ==
−
If fullscreen is enabled and the width or height is not supported (see [[love.window.checkMode]]), the window may be resized to the closest available resolution and a [[love.resize|resize]] event will be triggered. If the fullscreen type is "desktop", then the window will be automatically resized to the desktop resolution.
+
[[love.conf#window|love.conf]] may have more extensive documentation on the behavior of each window flag.
  
−
If you have disabled the window in [[conf.lua]] and use this functon to manually create the window, then you must not call any other [[love.graphics]].* function before this one. Doing so will result in undefined behavior and/or crashes because OpenGL cannot function properly without a window.
+
* If fullscreen is enabled and the width or height is not supported (see [[love.window.getFullscreenModes]]), the window may be resized to the closest available resolution and a [[love.resize|resize]] event will be triggered.
 +
 
 +
* If the fullscreen type is "desktop", then the window will be automatically resized to the desktop resolution.
 +
 
 +
* If the width and height is bigger than or equal to the desktop dimensions (this includes setting both to 0) and fullscreen is set to false, it will appear "visually" fullscreen, but it's not true fullscreen and [[love.window.getFullscreen]] will return false in this case. This also applies to [[love.window.updateMode]] as well.
 +
 
 +
* If you have disabled the window in [[Config_Files|conf.lua]] (i.e. <code>t.window = false</code>) and use this function to manually create the window, then you must not call any other [[love.graphics]].* function before this one. Doing so will result in undefined behavior and/or crashes because OpenGL cannot function properly without a window.
 +
 
 +
* In Android, the aspect ratio deducted from the width and the height is used to determine whetever the game run in landscape or portrait.
 +
 
 +
* Transparent backgrounds are currently not supported.
 +
 
 +
== Examples ==
 +
=== Make the window resizable with vsync disabled and a minimum width and height set. ===
 +
<source lang="lua">
 +
function love.load()
 +
    love.window.setMode(800, 600, {resizable=true, vsync=false, minwidth=400, minheight=300})
 +
end
 +
</source>
  
 
== See Also ==
 
== See Also ==
 
* [[parent::love.window]]
 
* [[parent::love.window]]
 
* [[love.window.getMode]]
 
* [[love.window.getMode]]
−
* [[love.window.getModes]]
+
* [[love.window.getFullscreenModes]]
 +
* [[love.resize]]
 
[[Category:Functions]]
 
[[Category:Functions]]
−
{{#set:Description=Changes the display mode.}}
+
{{#set:Description=Sets the display mode and properties of the window.}}
 
{{#set:Since=090}}
 
{{#set:Since=090}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.window.setMode}}
 
{{i18n|love.window.setMode}}

Revision as of 19:47, 4 July 2020

Available since LÖVE 0.9.0
Moved from love.graphics.setMode.


Sets the display mode and properties of the window.

If width or height is 0, setMode will use the width and height of the desktop.

Changing the display mode may have side effects: for example, canvases will be cleared and values sent to shaders with Shader:send will be erased. Make sure to save the contents of canvases beforehand or re-draw to them afterward if you need to.

Function

Synopsis

success = love.window.setMode( width, height, flags )

Arguments

number width
Display width.
number height
Display height.
table flags
The flags table with the options:
boolean fullscreen (false)
Fullscreen (true), or windowed (false).
FullscreenType fullscreentype ("desktop")
The type of fullscreen to use. This defaults to "normal" in 0.9.0 through 0.9.2 and to "desktop" in 0.10.0 and older.
number vsync (1)
Enables or disables vertical synchronisation ('vsync'): 1 to enable vsync, 0 to disable it, and -1 to use adaptive vsync (where supported). Prior to 11.0 this was a boolean flag, rather than a number.
number msaa (0)
The number of antialiasing samples.
boolean stencil (true)
Whether a stencil buffer should be allocated. If true, the stencil buffer will have 8 bits.
number depth (0)
The number of bits in the depth buffer.
boolean resizable (false)
True if the window should be resizable in windowed mode, false otherwise.
boolean borderless (false)
True if the window should be borderless in windowed mode, false otherwise.
boolean centered (true)
True if the window should be centered in windowed mode, false otherwise.
number display (1)
The index of the display to show the window in, if multiple monitors are available.
number minwidth (1)
The minimum width of the window, if it's resizable. Cannot be less than 1.
number minheight (1)
The minimum height of the window, if it's resizable. Cannot be less than 1.
Available since LÖVE 0.9.1
boolean highdpi (false)
True if high-dpi mode should be used on Retina displays in macOS and iOS. Does nothing on non-Retina displays. This is always enabled on Android.


Available since LÖVE 0.9.2
number x (nil)
The x-coordinate of the window's position in the specified display.
number y (nil)
The y-coordinate of the window's position in the specified display.


Available since LÖVE 11.3
boolean usedpiscale (true)
Disables LOVE's automatic DPI scaling on high-DPI displays when false. This only has an effect when the highdpi flag is set to true, since the OS (rather than LOVE) takes care of everything otherwise.


Available since LÖVE 0.9.1 and removed in LÖVE 0.10.0
boolean srgb (false)
Removed in 0.10.0 (set t.gammacorrect in conf.lua instead). True if sRGB gamma correction should be applied when drawing to the screen.


Returns

boolean success
True if successful, false otherwise.

Notes

love.conf may have more extensive documentation on the behavior of each window flag.

  • If fullscreen is enabled and the width or height is not supported (see love.window.getFullscreenModes), the window may be resized to the closest available resolution and a resize event will be triggered.
  • If the fullscreen type is "desktop", then the window will be automatically resized to the desktop resolution.
  • If the width and height is bigger than or equal to the desktop dimensions (this includes setting both to 0) and fullscreen is set to false, it will appear "visually" fullscreen, but it's not true fullscreen and love.window.getFullscreen will return false in this case. This also applies to love.window.updateMode as well.
  • If you have disabled the window in conf.lua (i.e. t.window = false) and use this function to manually create the window, then you must not call any other love.graphics.* function before this one. Doing so will result in undefined behavior and/or crashes because OpenGL cannot function properly without a window.
  • In Android, the aspect ratio deducted from the width and the height is used to determine whetever the game run in landscape or portrait.
  • Transparent backgrounds are currently not supported.

Examples

Make the window resizable with vsync disabled and a minimum width and height set.

function love.load()
    love.window.setMode(800, 600, {resizable=true, vsync=false, minwidth=400, minheight=300})
end

See Also


Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info

Retrieved from "http://www.love2d.org/w/index.php?title=love.window.setMode&oldid=25439"