Class Documentation
Screen |
1.0 |
ID_SCREEN |
Unspecified |
graphics/screen.h |
July 2001 |
Rocklyte Systems |
Rocklyte Systems, 1996-2001. 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. |
Hide | Hides a Screen from the visual display. |
Resize | Resizes the dimensions of a Screen object. |
SaveImage | Saves the image of a Screen to a data object. |
Show | Shows a Screen object on the visual display. |
Methods
The Screen class implements the following methods:
UpdatePalette | Updates an entire Screen palette to new colour values. |
WaitRastLine | Waits for the strobe to reach a specific line. |
WaitVBL | Waits for a vertical blank. |
Structure
The Screen object consists of the following public fields:
AmtColours | Tells you the total amount of colours used by a Screen object. |
Bitmap | Points to the Bitmap structure to use for direct drawing. |
BitsPerPixel | Tells you the number of bits-per-pixel used by a Screen object. |
BmpXOffset | Defines the horizontal coordinate of the Bitmap within a Screend display. |
BmpYOffset | Defines the vertical coordinate of the Bitmap within a Screen display. |
BytesPerPixel | Tells you the number of bytes-per-pixel used by a Screen object. |
Height | Defines the height of a Screen display. |
Width | Defines the width of a Screen display. |
XCoord | Defines the horizontal coordinate of a Screen display. |
YCoord | Defines the vertical coordinate of a 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.
|
|
UpdatePalette() |
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.
|
|
WaitRastLine() |
Waits for the strobe to reach a specific line. |
LONG Line | Vertical beam position to wait for. |
|
This method waits for the strobe to reach the scan-line specified in the
Line argument. The recognised range is dependent on the height of your screen,
e.g. 0-599 for a standard 800x600 screen. It is permissable to enter
negative values and values that exceed this range, but only do so if
absolutely necessary.
Not all graphics hardware will support this method. If this is the
case, WaitRastLine() will return immediately with ERR_NoSupport.
|
|
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: | AmtColours |
Short: | Tells you the total amount of colours used by a Screen object. |
Type: | LONG |
Status: | Read |
If you need to know the total amount of colours used by a Screen object
then you can read this field. Common return values are 256, 32768, 65536,
and 16777216.
|
|
Field: | Bitmap |
Short: | Points to the Bitmap structure to use for direct drawing. |
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: | BitsPerPixel |
Short: | Tells you the number of bits-per-pixel used by a Screen object. |
Type: | LONG |
Status: | Read |
This low-level field tells you the total number of bits-per-pixel (BPP)
used for each pixel in a Screen object. The number is closely tied to the
amount of colours used - for instance 15 bits equals 32,768 colours, 16 bits
equals 65,526 colours and so forth. The only time when the BitsPerPixel
setting bears no relationship to the number of colours are when extra bits
are being used for colour management.
|
|
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: | BytesPerPixel |
Short: | Tells you the number of bytes-per-pixel used by a Screen object. |
Type: | LONG |
Status: | Read |
This low-level field tells you the total number of bytes used for each
pixel in a Screen object. For instance, if 16.8 million colours are used
then you will most likely get a return value of 3.
|
|
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: | 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: | 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.
|
|