Class Documentation

Name:Screen
Version:1.0
ID:ID_SCREEN
Status:Stable
Include:graphics/screen.h
Date:February 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2003. 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.
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:

SetDisplay  Changes the current screen mode.
SetGamma  Sets the display gamma levels.
SetGammaLinear  Sets the display gamma level using a linear algorithm.
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 graphics hardware clock speed.
DAC  .
Display  String describing the display (e.g. model name of the monitor).
Display  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 a screen display.
Manufacturer  String describing the manufacturer of the graphics hardware.
RefreshRate  This field manages the screen refresh rate.
Width  Defines the width of a screen display.
WindowHandle  Refers to a screen object's window handle, if relevant.
XCoord  Defines the horizontal coordinate of a screen display.
YCoord  Defines the vertical coordinate of a screen display.
Action:Hide
Short: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.


Method:SetGamma()
Short:Sets the display gamma levels.
Arguments:
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.

Result
ERR_Okay  Gamma correction set successfully.
ERR_Args  Invalid arguments were specified.
ERR_NoSupport  The graphics hardware does not support gamma correction.

Method:UpdatePalette()
Short:Updates an entire Screen palette to new colour values.

Normally when you write changes to the Screen->Bitmap->Palette array, there will be no visible effect on the display for Types of 256 colours or less. If you want your changes to be visible, you will need to call UpdatePalette(). This will cause the Screen display to be updated and reflect the new palette values.

This method has no visible effect on RGB based screens.


Method:WaitVBL()
Short: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

Field:Chipset
Short:String describing the graphics chipset.
Type:STRING
Status:Get

Field:Clock
Short:String describing the graphics hardware clock speed.
Type:STRING
Status:Get

Field:DAC
Short:.
Type:STRING
Status:Get

Field:Display
Short:String describing the display (e.g. model name of the monitor).
Type:STRING
Status:Get

Field:Display
Short:String describing the display manufacturer.
Type:STRING
Status:Get

Field:DriverCopyright
Short:String containing copyright information on the graphics driver software.
Type:STRING
Status:Get

Field:DriverVendor
Short:String describing the vendor of the graphics driver.
Type:STRING
Status:Get

Field:DriverVersion
Short:String describing the version of the graphics hardware driver.
Type:STRING
Status:Get

Field:Height
Short:Defines the height of a 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

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:Width
Short:Defines the width of a 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 a 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 a 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.