Class Documentation
Screen |
1.0 |
ID_SCREEN |
Stable |
graphics/screen.h |
August 2004 |
Rocklyte Systems |
Rocklyte Systems, 1996-2004. All rights reserved. |
Description
The Screen represents an area of displayable video memory. Although it
is a very complex structure, it is fairly simple to initialise. In fact
it is possible to initialise a Screen using an empty structure and accept
all the user defaults (which we recommended if possible). For more demanding
applications however you may often need to specify a few fields. Before doing
so, make sure that you understand how each field operates and what
implications setting them may bring. Where possible try to avoid setting
field values, as the user default should always be considered as
acceptable.
It is perfectly acceptable to initialise multiple Screen objects and put
them on display, but due to memory restrictions, chances of failure could be
high when doing this in certain environments. When programming for Athene, it
is recommended that the utilisation of Screen objects is avoided in favour of
using the Render class. which is much lighter on memory usage.
Screens that are created as shared objects are available for any
application or object to draw graphics to, so bear in mind the implications
of creating a shared Screen.
Actions
The Screen class supports the following actions:
Activate | Activating a Screen has the same effect as showing it on the display. |
Clear | Clears a Screen's image data. |
Disable | Disables the screen display (goes into power saving mode). |
Enable | Restores the screen display from power saving mode. |
Flush | Flush pending graphics operations to the display. |
GetUnlistedField | Retrieve formatted information from the screen. |
Hide | Hides a Screen from the visual display. |
Move | Moves a screen to a new offset on the display. |
Redimension | Moves and resizes a screen object in a single action call. |
Resize | Resizes the dimensions of a screen object. |
SaveImage | Saves the image of a Screen to a data object. |
SaveToObject | Writes the current screen settings to another object. |
Show | Shows a Screen object on the visual display. |
Methods
The Screen class implements the following methods:
ScreenSizeHints | Sets the width and height restrictions for the host window (hosted environments only). |
SetDisplay | Changes the current screen mode. |
SetGamma | Sets the display gamma levels. |
SetGammaLinear | Sets the display gamma level using a linear algorithm. |
SetMonitor | Changes the default monitor settings. |
UpdatePalette | Updates an entire Screen palette to new colour values. |
WaitVBL | Waits for a vertical blank. |
Structure
The Screen object consists of the following public fields:
Bitmap | Points to the Bitmap structure to use for direct drawing to the video display. |
BmpXOffset | Defines the horizontal coordinate of the Bitmap within a Screend display. |
BmpYOffset | Defines the vertical coordinate of the Bitmap within a Screen display. |
CertificationDate | String describing the date of the graphics driver's certification. |
Chipset | String describing the graphics chipset. |
Clock | String describing the graphic hardware's clock speed. |
DAC | Describes the graphic card's Digital to Analog Convertor. |
Display | String describing the display (e.g. model name of the monitor). |
DisplayManufacturer | String describing the display manufacturer. |
DriverCopyright | String containing copyright information on the graphics driver software. |
DriverVendor | String describing the vendor of the graphics driver. |
DriverVersion | String describing the version of the graphics hardware driver. |
Height | Defines the height of the screen display. |
Manufacturer | String describing the manufacturer of the graphics hardware. |
RefreshRate | This field manages the screen refresh rate. |
Title | Sets the window title (hosted environments only). |
Width | Defines the width of the screen display. |
WindowHandle | Refers to a screen object's window handle, if relevant. |
XCoord | Defines the horizontal coordinate of the screen display. |
YCoord | Defines the vertical coordinate of the screen display. |
Hide |
Hides a Screen from the visual display. |
Calling this action will hide a Screen from the visual display. If the
hidden Screen was at the front of the display and there is a Screen object
behind it, then the next underlying Screen will be displayed. If there are
no other Screens available then the visual display will be blank after
calling this action.
|
|
SetDisplay() |
Changes the current screen mode. |
LONG XCoord | Horizontal offset of the display, relative to its default position. |
LONG YCoord | Vertical offset of the display, relative to its default position. |
LONG Width | Width of the display. |
LONG Height | Height of the display. |
LONG InsideWidth | Internal display width (must be equal to or greater than the screen width). |
LONG InsideHeight | Internal display height (must be equal to or greater than the screen height). |
DOUBLE RefreshRate | Refresh rate, measured in floating point format for precision. |
LONG Flags | Special flags. |
|
The SetDisplay method changes the current display settings for the screen.
It can alter the position and screen dimensions and the display refresh rate.
The new settings are applied immediately, although minor delays are possible
while the graphics card and monitor adjust to the changes.
To keep any of the screen settings at their current value, set the
appropriate parameters to zero to leave them unchanged. Only the parameters
that you set will be used.
If the display parameters do not match with a valid screen mode - for instance
if you request a screen size of 1280x1024 and the nearest equivalent is 1024x768,
the SetDisplay method will automatically adjust to match against the nearest screen
size.
Only the original owner of the screen object is allowed to change the screen
settings.
ERR_Okay | Screen mode set successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_Failed | Failed to switch to the requested display mode. |
|
|
SetGamma() |
Sets the display gamma levels. |
DOUBLE Red | Gamma correction for the red gun. |
DOUBLE Green | Gamma correction for the green gun. |
DOUBLE Blue | Gamma correction for the blue gun. |
LONG Flags | Optional flags. |
|
The SetGamma method controls the gamma correction levels for the display.
You can set individual gamma levels for the red, green and blue colour guns at
floating point precision. The default gamma level for each gun is 1.0; the
minimum value is 0.0 and the maximum value is 100.
If you would like to know the current gamma correction settings, please refer to
the GammaRed, GammaGreen and GammaBlue fields.
ERR_Okay | Gamma correction set successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_NoSupport | The graphics hardware does not support gamma correction. |
|
|
SetMonitor() |
Changes the default monitor settings. |
STRING Name | The name of the display. |
LONG MinH | The minimum horizontal scan rate. Usually set to 31. |
LONG MaxH | The maximum horizontal scan rate. |
LONG MinV | The minimum vertical scan rate. Usually set to 50. |
LONG MaxV | The maximum vertical scan rate. |
LONG AutoDetect | Set to TRUE if the monitor settings should be auto-detected on startup. |
|
Use the SetMonitor method to change the settings that configure the user's
monitor display. You can set the model name of the monitor and the frequencies
that are supported by it. Altering the display frequencies will affect the
available display resolutions, as well as the maximum allowable refresh rate.
An AutoDetect option is available, which if set to TRUE, causes the display
settings to be automatically detected when the Athene desktop is loaded at startup.
If Athene cannot detect the correct settings for the plugged-in display, it
reverts to the default display settings.
This method does not work on hosted systems. All arguments passed to
this method are optional (set a value to zero if you do not want to change it).
ERR_Okay | Monitor settings applied successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_NoSupport | The graphics hardware does not support gamma correction. |
|
|
UpdatePalette() |
Updates an entire Screen palette to new colour values. |
If you write changes to the Screen->Bitmap->Palette array, there will
be no visible effect if the display is of 256 colours or less. If you want your
changes to be visible, you will need to call UpdatePalette(). This will cause
the display to be updated and reflect the new palette values.
This method has no visible effect on RGB based screens.
|
|
WaitVBL() |
Waits for a vertical blank. |
This method waits for the strobe to reach the vertical blank area at the
bottom of the display. Not all graphics hardware will support this method.
If this is the case, WaitVBL() will return immediately with ERR_NoSupport.
|
|
Field: | Bitmap |
Short: | Points to the Bitmap structure to use for direct drawing to the video display. |
Type: | *Bitmap |
Status: | Read |
The Bitmap object sets display information on how the data will be
shown on screen. It holds details on the width, height, type, number of
colours and so on. The Screen inherits and uses all of these fields, so
you can set them on initialisation as per normal.
The Bitmap's Width and Height can be larger than the Screen area, but
must never be smaller than the Screen area.
|
|
Field: | BmpXOffset |
Short: | Defines the horizontal coordinate of the Bitmap within a Screend display. |
Type: | LONG |
Status: | Read/Init |
This field defines the horizontal offset for the
Bitmap, which is positioned 'behind' the Screen. If you
want to achieve hardware scrolling, you will need to call the Move action on
the Bitmap in order to change this value and update the display.
|
|
Field: | BmpYOffset |
Short: | Defines the vertical coordinate of the Bitmap within a Screen display. |
Type: | LONG |
Status: | Read/Init |
This field defines the vertical offset for the
Bitmap, which is positioned 'behind' the Screen. If you
want to achieve hardware scrolling, you will need to call the Move action on
the Bitmap in order to change this value and update the display.
|
|
Field: | CertificationDate |
Short: | String describing the date of the graphics driver's certification. |
Type: | STRING |
Status: | Get |
The string in this field describes the date on which the graphics card
driver was certified. If this information is not available from the driver,
a NULL pointer is returned.
|
|
Field: | Chipset |
Short: | String describing the graphics chipset. |
Type: | STRING |
Status: | Get |
The string in this field describes the graphic card's chipset. If this
information is not retrievable, a NULL pointer is returned.
|
|
Field: | Clock |
Short: | String describing the graphic hardware's clock speed. |
Type: | STRING |
Status: | Get |
The string in this field describes the graphic card's clock device. If this
information is not retrievable, a NULL pointer is returned.
|
|
Field: | DAC |
Short: | Describes the graphic card's Digital to Analog Convertor. |
Type: | STRING |
Status: | Get |
The string in this field describes the graphic card's Digital to Analog
Convertor. If the DAC is not known, a NULL pointer is returned.
|
|
Field: | Display |
Short: | String describing the display (e.g. model name of the monitor). |
Type: | STRING |
Status: | Get |
The string in this field describes the display device that is connected to
the user's graphics card. If this information is not detectable, a NULL
pointer is returned.
|
|
Field: | DisplayManufacturer |
Short: | String describing the display manufacturer. |
Type: | STRING |
Status: | Get |
The string in this field returns the name of the manufacturer that created
the user's display device. If this information is not detectable, a NULL
pointer is returned.
|
|
Field: | DriverCopyright |
Short: | String containing copyright information on the graphics driver software. |
Type: | STRING |
Status: | Get |
The string in this field returns copyright information related to the
graphics driver. If this information is not available, a NULL pointer is
returned.
|
|
Field: | DriverVendor |
Short: | String describing the vendor of the graphics driver. |
Type: | STRING |
Status: | Get |
The string in this field returns the name of the vendor that supplied
the graphics card driver. If this information is not available, a NULL
pointer is returned.
|
|
Field: | DriverVersion |
Short: | String describing the version of the graphics hardware driver. |
Type: | STRING |
Status: | Get |
The string in this field describes the graphic driver's version number.
If this information is not detectable, a NULL pointer is returned.
|
|
Field: | Height |
Short: | Defines the height of the screen display. |
Type: | LONG |
Status: | Read/Init |
This field defines the height of a Screen display. This is known as the
'viewport' that the Bitmap data is displayed through. If the Height is too
large or difficult to support, then it will be automatically restricted to a
value that the display hardware can handle.
|
|
Field: | Manufacturer |
Short: | String describing the manufacturer of the graphics hardware. |
Type: | STRING |
Status: | Get |
The string in this field returns the name of the manufacturer that created
the user's graphics card. If this information is not detectable, a NULL
pointer is returned.
|
|
Field: | RefreshRate |
Short: | This field manages the screen refresh rate. |
Type: | FLOAT |
Status: | Read/Set |
The value in this field reflects the refresh rate of the currently
active screen display.
|
|
Field: | Title |
Short: | Sets the window title (hosted environments only). |
Type: | STRING |
Status: | Set |
The Title field defines the window title that is used when a screen is
opened in a hosted environment.
|
|
Field: | Width |
Short: | Defines the width of the screen display. |
Type: | LONG |
Status: | Read/Init |
This field defines the width of a screen display. This is known as the
'viewport' that the bitmap data is displayed through. If the Width is too
large or difficult to support, then it will be automatically restricted to a
value that the display hardware can handle.
|
|
Field: | WindowHandle |
Short: | Refers to a screen object's window handle, if relevant. |
Type: | LONG |
Status: | Get/Init |
This field refers to the window handle of a screen object, but only if
such a thing is relevant to the platform that the system is running on.
Currently, this field is only usable when creating a screen within an X11
window manager or Microsoft Windows.
It is possible to set the WindowHandle field prior to initialisation
if you want a screen object to be based on a window that already exists.
|
|
Field: | XCoord |
Short: | Defines the horizontal coordinate of the screen display. |
Type: | LONG |
Status: | Read/Init |
The XCoord field defines the horizontal hardware coordinate for a screen
display. A setting of 0 in this field is sufficient for the majority of
programs. Negative values are allowed. If you go outside of the displayable
range when setting this field, the value will be automatically restricted.
The Move action can also be used to adjust the position of a screen
display.
|
|
Field: | YCoord |
Short: | Defines the vertical coordinate of the screen display. |
Type: | LONG |
Status: | Read/Init |
The YCoord field defines the vertical hardware coordinate for a screen
display. A setting of 0 in this field is sufficient for the majority of
programs. Negative values are allowed. If you go outside of the displayable
range when setting this field, the value will be automatically restricted.
The Move action can also be used to adjust the position of a screen
display.
|
|