DisplayOverlord Module
The DisplayOverlord module's methods and properties handle all video device enumeration and manipulation. Display Overlord takes much of the guesswork out of preparing a fullscreen environment but also intentionally limits functionality to prevent common problems. The DisplayOverlord.FadeToSolid method simply fades all attached displays simultaneously for example, and the DisplayOverlord.Capture methods also affect all displays, essentially disabling everything but the targeted device. Simply put, these classes only "capture" one display at a time, but do so in a consistent and safe manner.
Important: There appears to be some synchronization issues with the REALbasic framework when display geometry is changed from any thread other than the main thread. Capturing, releasing, or fading displays outside of the main thread is not recommended. If you must initiate these actions from a Thread, the simplest solution is to start a Timer, and call the Display Overlord methods from the Timer's Action event.
Note: All properties and methods listed below have public scope and must be prefixed with the DisplayOverlord namespace and dot notation.
Properties
-
Captured As Boolean
Returns True if a display is currently captured (short cut for DisplayOverlord.CapturedDevice <> Nil) -
CapturedBrightness As Integer
Sets the brightness level for the captured display. This value is a percentage of the desktop gamma, where 0 is black, and 100 is equal to the desktop gamma. Numbers higher than 100 over-saturate the display (making it brighter). This value can be set at any time but has no effect until a display is captured. The value is capped internally between 0 and 200. -
CapturedDevice As DisplayOverlordDevice
Returns the captured display, or Nil if the no display is captured. -
DeviceCount As Integer
The total number of display devices attached to the system. -
Faded As Boolean
Returns True if the displays are currently faded to black. -
MacDisableHideWhenCaptured As Boolean = True
If True (default setting), the Command-H key combo is disabled on Mac OS X while displays are captured. This flag must be set before capturing a display to have any affect. It can be disabled while a display is captured however. -
MacDisableQuitWhenCaptured As Boolean
If True, the Command-Q key combo is disabled on Mac OS X while displays are captured. This flag must be set before capturing a display to have any affect. In can be disabled while a display is captured however. -
MacDrawWindowsOnTop As Boolean = True
When set to True (default setting), this will force all of your application's windows to draw on top of the shielding window that covers captured displays. This functionality is really only provided to allow a single "fullscreen" window to draw on top of a captured display (your game window, etc.). Multiple layered windows and certain UI elements may not behave normally in the captured environment.
Important: If you are drawing to a fullscreen OpenGL context via declares or plugins be sure to set this property to False before capturing a display to avoid unpredictable behaviour. Fullscreen OpenGL generally doesn't get along with regular windows.
Methods
-
Capture ( index As Integer, mode As DisplayOverlordMode ) As Boolean
Captures the display at the specified index using the attributes in the supplied DisplayOverlordMode and returns True if successful. The mode parameter would typically be an instance returned by the DisplayOverlordDevice.Mode function, but can be modified or created from scratch to request more specific settings. Using refresh rate or depth values of 0 within mode will attempt to preserve the respective desktop settings.
If the requested settings are not available, the device will be captured using the closet match. You can check the actual captured settings by reading the properties of DisplayOverlord.CapturedDevice once the display is successfully captured.
Display index constants:- DisplayOverlord.MainDisplay : Capture the main display.
-
Capture ( index As Integer, width As Integer, height As Integer, refreshrate As Integer = 0, depth As Integer = 0 ) As Boolean
Captures the display at the specified index using the supplied parameters and returns True if successful. This function is provided for "quick & dirty" display capturing on known systems or for rough prototyping. For more robust captures, first enumerate the available devices and modes, then pass a DisplayOverlordMode instance to the DisplayOverlord.Capture method above. Using a refreshrate or depth value of 0 (default) will attempt to preserve the respective desktop setting.
If the requested settings are not available, the device will be captured using the closet match. You can check the actual captured settings by reading the properties of DisplayOverlord.CapturedDevice once the display is successfully captured.
Display index constants:- DisplayOverlord.MainDisplay : Capture the main display.
-
Device ( index As Integer ) As DisplayOverlordDevice
Returns a DisplayOverlordDevice instance that represents the display at the given index or Nil if index is out of range. Valid indexes range from 0 (the main display) to DisplayOverlord.DeviceCount-1.
Device index constants:- DisplayOverlord.MainDisplay : Returns the main display, or Nil if no displays are attached.
-
FadeToNormal ( fadetime As Double )
Fades all displays from black to their appropriate desktop or captured gamma. The fadetime parameter is the total time in seconds the fade will last. -
FadeToSolid ( fadetime As Double )
Fades all displays from their current gamma to black. The fadetime parameter is the total time in seconds the fade will last. -
Release
Releases all displays and restores the user's desktop settings. Note that this will not restore the desktop gamma levels if the displays are currently faded to black. Use the DisplayOverlord.FadeToNormal method after releasing to restore the gamma in this case.