Change the desktop resolution to provide better rendering performance or to avoid having your application resized (and possibly stretched) to fill the users desktop.


First available in version 3.0 build 2039.

Input Parameters:

width - The new desktop width in pixels.

height - The new desktop height in pixels.

colorDepth - The new color depth, expressed as bits per pixel Valid values include: 2, 4, 8, 16, 24, and 32.

refreshRate - [Optional] - The new refresh rate. If no value is provided, the current refresh rate will be used. This argument is not required in DirectDraw mode.

permanent - [Optional] - A boolean value that indicates that the resolution change should be permanent (TRUE) instead of the default temporary (FALSE). Valid values include: true and false.

useDirectDraw - [Optional] - A boolean value that indicates whether you want to Use DirectDraw instead of the Windows API to change the screen resolution. An error will be returned if DirectDraw is not supported. Valid values include: true and false.

Output Parameters:

No output parameters.

Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.Desktop.changeResolution( paramsObject [, callbackParamsObject] [, errorParamsObject] );

Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.Desktop.changeResolution( paramsObject );


Settting the screen resolution via the Win32 API method will work on all systems where the DirectDraw optin will only work where DirectDraw 7 (or better is installed). Essentially this will cover most modern systenms.

The Win32 API method gives you control over the refresh rate, but also requires that you restore it to avoid messing up the users display. DirectDraw doesn't let you set or read the monitor refresh rate so it's a bit simpler. Because Win32 lets you specify different refresh rates, more resolutions are generally possible, see ssGlobals.ssDesktopDisplayModes for an example list of available resolutions.

Changes made to the resolution via DirectDraw will automatically revert to the default display settings when your app ends, the Win32 method allows you to make resolution changes permanent (persist after your application ends).


ssCore.Desktop.changeResolution({width:800, height:600, colorDepth:32, useDirectDraw:true});