@DATABASE "Screen"
@AUTHOR   "Paul Manias"
@NODE     "Main" "Object: Screen"

@{b}@{u}OBJECT DOCUMENTATION@{uu}@{ub}
Name:      @{"SCREEN" LINK "Description"}
Version:   0.9 Beta
Date:      October 1997
Author:    Paul Manias
Copyright: DreamWorld Productions, 1996-1997.  All rights reserved.

@{b}@{u}CHANGES VERSION 0.9B@{uu}@{ub}
Edited:  Screen description.
         Screen->Palette

Added:   Screen->Attrib:BLANKPALETTE.
         Screen->Switch

Removed: Screen->AmtColours
         Screen->ByteWidth
         Screen->LineMod
         Screen->PicHeight
         Screen->Planes
         Screen->PlaneMod
         Screen->PlaneSize
         Screen->ScrType
         Screen->Width

Renamed: ScrHeight, ScrWidth to Height, Width.
         PicX/YOffset to BmpX/YOffset

@EndNode
---------------------------------------------------------------------------
@NODE  "Description" "Object: Screen"

@{b}@{u}OBJECT@{ub}@{uu}
Name:    Screen
Module:  @{"Screens" LINK "GMSDev:AutoDocs/Screens.guide/Functions"}
Version: 1
Type:    Complex

@{b}@{u}DESCRIPTION@{ub}@{uu}
The  Screen  represents  the values of an area of displayable video memory.
Although  it is probably the most complex structure, it is fairly simple to
initialise.   Indeed  it  is  possible to initialise a Screen by passing an
empty  Screen  structure  to  Init()  and  accepting  all the user defaults
(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.

@{b}@{u}NOTE@{uu}@{ub}
The MemPtrX fields can change without notice while your program is running.
This  is  because the memory pointers move around when the screen is hidden
or  moved  from the display.  To ensure the screen does not move from video
memory you can use the LockVideo() action.

@{b}@{u}ACTIONS@{uu}@{ub}
The Screen object supports the following actions:

     @{"CopyStructure()" LINK "GMSDev:AutoDocs/Kernel.guide/CopyStructure()"} Copy screen details to another object.
     @{"Display()      " LINK "GMSDev:AutoDocs/Kernel.guide/Display()"      } Display a screen on a monitor or TV.
     @{"Free()         " LINK "GMSDev:AutoDocs/Kernel.guide/Free()"         } Free a Screen from the system.
     @{"Get()          " LINK "GMSDev:AutoDocs/Kernel.guide/Get()"          } Get a new Screen structure.
     @{"Hide()         " LINK "GMSDev:AutoDocs/Kernel.guide/Hide()"         } Hide a screen from view.
     @{"Init()         " LINK "GMSDev:AutoDocs/Kernel.guide/Init()"         } Initialise a Screen.
     @{"Lock()         " LINK "GMSDev:AutoDocs/Kernel.guide/Lock()"         } Lock a screen from other tasks.
     @{"Unlock()       " LINK "GMSDev:AutoDocs/Kernel.guide/Unlock()"       } Unlock a locked screen.

@{b}@{u}FUNCTIONS@{uu}@{ub}
Some functions that support the Screen object are:

     @{"LockVideo()    " LINK "GMSDev:AutoDocs/Screens.guide/LockVideo()"    }
     @{"RefreshScreen()" LINK "GMSDev:AutoDocs/Screens.guide/RefreshScreen()"}
     @{"RemakeScreen() " LINK "GMSDev:AutoDocs/Screens.guide/RemakeScreen()" }
     @{"ResetPicture() " LINK "GMSDev:AutoDocs/Screens.guide/ResetPicture()" }
     @{"UnlockVideo()  " LINK "GMSDev:AutoDocs/Screens.guide/UnlockVideo()"  }

@{b}@{u}STRUCTURE@{ub}@{uu}
The Screen structure consists of the following public fields:

     @{"Attrib    " LINK "GS_Attrib"    } Special Attributes are?
   + @{"Bitmap    " LINK "GS_Bitmap"    } Pointer to bitmap structure (for blitting).
     @{"BmpXOffset" LINK "GS_BmpXOffset"} Offset of the horizontal axis.
     @{"BmpYOffset" LINK "GS_BmpXOffset"} Offset of the vertical axis.
     @{"Height    " LINK "GS_ScrWidth"  } The height of the visible screen window.
     @{"MemPtr1   " LINK "GS_MemPtr"    } Pointer to screen 1
     @{"MemPtr2   " LINK "GS_MemPtr"    } Pointer to screen 2 (doubled buffer)
     @{"MemPtr3   " LINK "GS_MemPtr"    } Pointer to screen 3 (tripled buffer)
     @{"Palette   " LINK "GS_Palette"   } Pointer to the screen palette.
     @{"Rasterlist" LINK "GS_Rasterlist"} Pointer to a rasterlist.
     @{"ScreenLink" LINK "GS_ScreenLink"} Pointer to a linked screen.
     @{"ScrMode   " LINK "GS_ScrMode"   } What screen mode is it?
     @{"Switch    " LINK "GS_Switch"    } Set if ready to switch display buffers.
     @{"Task      " LINK "GS_Task"      } Task that owns this screen.
     @{"Width     " LINK "GS_ScrWidth"  } The width of the visible screen window.
     @{"XOffset   " LINK "GS_XOffset"   } Hardware co-ordinate for TOS.
     @{"YOffset   " LINK "GS_XOffset"   } Hardware co-ordinate for LOS.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Attrib" "Object: Screen"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Attrib
Type:        LONG
Inheritance: Some flags can be set by the user.
On Change:   Cannot change after initialisation.
Status:      Read/IWrite

@{b}@{u}DESCRIPTION@{uu}@{ub}
Defines  the  special attributes for the screen.  Currently available flags
are:

@{u}BLANKPALETTE@{uu}
Any  screen  with  256  colours  or  less will open with a pre-defined user
palette  if  Screen->Paltte  is NULL.  By setting this flag you can dismiss
this and the screen will open with a pure black palette.

@{u}BLKBDR@{uu}
Turns  all  colours  outside  of the display window to black.  Works on AGA
only.

@{u}CENTRE@{uu}
Centres  the  screen  by calculating the correct offsets for ScrXOffset and
ScrYOffset  for any screen mode.  The calculated values will over-write any
values already set in these fields.

@{u}DBLBUFFER@{uu}
Allocates  an  extra  screen  buffer  which  is placed in MemPtr2.  See the
SwapBuffers() function for more information on double buffering.

@{u}HSCROLL@{uu}
Set if you want to use horizontal picture scrolling.

@{u}NOSCRBDR@{uu}
Allows  sprites  and  other  displayable  objects  to appear outside of the
viewport.  Works on AGA only.

@{u}SBUFFER@{uu}
Allocates  extra space to allow you to horizontally scroll up to 50 screens
in either X direction.

@{u}SPRITES@{uu}
Set if you intend to use sprites with this screen.

@{u}TPLBUFFER@{uu}
Allocates  two  extra buffers which are placed in MemPtr2 and MemPtr3.  See
the SwapBuffers() for more information on triple buffering.

Note:  Never set the DBLBUFFER flag in conjunction with the TPLBUFFER flag.

@{u}VSCROLL@{uu}
Set if you want to use vertical picture scrolling.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Bitmap" "Object: Screen"


The  Bitmap is the display data that shows through onto screen.  The Bitmap
can  be  larger  than  the  Screen area, but must never be smaller than the
Screen area.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_BmpXOffset" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:     BmpXOffset, BmpYOffset
Type:      WORD
On Change: RemakeScreen()
Status:    Read/Write

@{b}@{u}DESCRIPTION@{uu}@{ub}
These  two  fields  set the offsets for the Bitmap "behind" the Screen.  If
you  want  to do any sort of hardware scrolling, you will want to use these
values in conjunction with MoveBitmap().

@EndNode
---------------------------------------------------------------------------
@NODE "GS_MemPtr" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:       MemPtr1, MemPtr2, MemPtr3
Type:        APTR
On Change:   Cannot change after initialisation.
Status:      Read/IWrite
Inheritance: Allocated by Init().

@{b}@{u}DESCRIPTION@{uu}@{ub}
These  fields point to the screen display data.  They should be NULL if you
want Init() to allocate the memory for you (highly recommended).  Otherwise
it  will  be assumed that the values are valid pointers to video memory and
screen based functions will use them as such.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Palette" "Object: Screen"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Palette
Type:        LONG *
On Change:   UpdatePalette()
Inheritance: Pre-defined user palette.
Status:      Read/Write

@{b}@{u}DESCRIPTION@{uu}@{ub}
Points  to  the  palette  for  this  screen.   Your  palette  array must be
represented  in 24 bit colours (0x00RRGGBB).  The format of the array looks
like this:

  PALETTE, <AmtColours>,
  0x00RRGGBB,
  ...

Example:

  LONG Palette[] = {
    PALETTE, 4,
    0x292894, 0x29f8f8, 0x499249, 0x392423
  };

If  you  do  not  set  this field then a user palette will be allocated and
placed   in   this   field.   If  you  specify  the  BLANKPALETTE  flag  in
Screen->Attrib, then you will get a black palette.

@{b}@{u}NOTE@{uu}@{ub}
If  the screen type is of CHUNKY15 or better, this field will be ignored as
colours are represented in the pixels, not a palette.

@{b}@{u}SEE ALSO@{uu}@{ub}
Bitmap: @{"AmtColours" LINK "GMSDev:AutoDocs/Objects/Bitmap.guide/BMP_AmtColours"}

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Rasterlist" "Object: Screen"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Rasterlist
Type:        APTR
On Change:   Cannot change by direct means after initialisation.
Status:      Read/Write
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
Points  to  a valid rasterlist structure, or NULL.  Rasterlists are made up
of  instructions  that  are  executed  as the monitor beam travels down the
screen.  See InitRasterlist() for more information on rasterlists.

To  change  the  current  rasterlist  to  another, call RemoveRasterList(),
write the Rasterlist field then call InitRasterlist().

To update an existing rasterlist, call UpdateRasterlist().

@EndNode
---------------------------------------------------------------------------
@NODE "GS_ScreenLink" "Object: Screen"

@{b}@{u}FIELD@{uu}@{ub}
Name:      ScreenLink
Type:      struct Screen *
On Change: Cannot change after initialisation.
Status:    Read/IWrite

@{b}@{u}DESCRIPTION@{uu}@{ub}
If  you  want  to  set  up  a  second screen at a different position in the
viewport,  or  create  an  extra  (double)  playfield,  point  to  the next
Screen structure here.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_ScrMode" "Object: Screen"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrMode
Type:        WORD
Inheritance: User default.
On Change:   Cannot change after initialisation.
Status:      Read/Write

@{b}@{u}DESCRIPTION@{uu}@{ub}
Defines the display mode for the screen.  If you do not fill in this field,
you will get the user's default resolution.

This  field  does  not  allow  programmed  mode  promotion - this matter is
handled  internally  and  by user selections in GMSPrefs.  You cannot force
mode promotion from inside your program.  NB:  If you require compatibility
for  NTSC,  set ScrHeight to 200 (or accept the user default for ScrHeight)
and assume that the user has selected NTSC mode promotion in GMSPrefs.

@{u}LORES@{uu}
Specifies a low resolution screen.

@{u}HIRES@{uu}
Specifies a high resolution screen (1/2 pixels).

@{u}SHIRES@{uu}
Specifies a super-high resolution screen (1/4 pixels).

@{u}LACED@{uu}
Creates an interlaced display (1/2 pixels).

@{u}HAM@{uu}
Sets the Amiga only Hold And Modify mode.  The amount of colours you get is
dependant  on  the  amount  of  planes  in  the  screen.  Works for planar/
interleaved screens only.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Switch" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:  Switch
Type:   WORD
Status: Read/Write

@{b}@{u}DESCRIPTION@{uu}@{ub}







@{b}@{u}SEE ALSO@{uu}@{ub}
Screens: @{"WaitSwitch()"      LINK "GMSDev:AutoDocs/Screens.guide/WaitSwitch()"}
Theory:  @{"Display Buffering" LINK "GMSDev:AutoDocs/Screens.guide/DisplayBuffering"}

@EndNode
---------------------------------------------------------------------------
@NODE "GS_XOffset" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:       XOffset, YOffset
Type:        WORD
On Change:   RemakeScreen()
Status:      Read/Write
Inheritance: None.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies  the  hardware offset for the screen.  These two values are added
to  the  user's  screen  offset  in  GMSPrefs.   A setting of 0,0 should be
sufficient,  unless  you  are  going  to  create  an extra large screen (eg
overscan).  Negative values are allowed.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Task" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:       Task
Type:        struct DPKTask *
On Change:   Cannot change after initialisation.
Status:      Read Only.
Inheritance: Task of initialisation.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Points  to  a DPKTask structure that identifies the task owning this screen
structure.

@EndNode
---------------------------------------------------------------------------
@NODE "GS_Width" "Object: Screen"

@{b}@{u}FIELDS@{uu}@{ub}
Names:       Width, Height
On Change:   RemakeScreen()
Status:      Read/Write
Inheritance: User default.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Defines  the  screen  height  and  width.   This is the "viewport" that the
picture  data  is  displayed  through.   The  width  of  the screen must be
divisible by 16 for ILBM and Planar modes.

@{b}@{u}SEE ALSO@{uu}@{ub}
Bitmap: @{"Width"  LINK "GMSDev:AutoDocs/Objects/Bitmap.guide/BMP_Width"}
        @{"Height" LINK "GMSDev:AutoDocs/Objects/Bitmap.guide/BMP_Height"}

@EndNode
---------------------------------------------------------------------------