@DATABASE "Screens" @AUTHOR "Paul Manias" @NODE "Main" "Screens Documentation" Name: @{"SCREENS" LINK "Functions"} AUTODOC Version: 0.7 Beta. Date: 6 July 1997 Author: Paul Manias Copyright: DreamWorld Productions, 1996-1997. All rights reserved. Notes: This document is still being written and will contain errors in a number of places. The information within cannot be treated as official until this autodoc reaches version 1.0. @EndNode --------------------------------------------------------------------------- @NODE "Functions" "Screens Functions" @{b}STRUCTURES@{ub} @{"GameScreen" LINK "GameScreen"} @{b}FUNCTIONS@{ub} @{"AddScreen()" LINK "AddScreen()"} @{"AllocVideoMem()" LINK "AllocVideoMem()"} @{"BlankOn()" LINK "BlankOn()"} @{"BlankOff()" LINK "BlankOff()"} @{"DeleteScreen()" LINK "DeleteScreen()"} @{"FreeVideoMem()" LINK "FreeVideoMem()"} @{"GetScreen()" LINK "GetScreen()"} @{"GetScrType()" LINK "GetScrType()"} @{"HideDisplay()" LINK "HideDisplay()"} @{"MovePicture()" LINK "MovePicture()"} @{"RefreshScreen()" LINK "RefreshScreen()"} @{"RemakeScreen()" LINK "RemakeScreen()"} @{"ResetPicture()" LINK "ResetPicture()"} @{"ReturnDisplay()" LINK "ReturnDisplay()"} @{"ShowScreen()" LINK "ShowScreen()"} @{"SwapBuffers()" LINK "SwapBuffers()"} @{"TakeDisplay()" LINK "TakeDisplay()"} @{"WaitVBL()" LINK "WaitVBL()"} @{"WaitRastLine()" LINK "WaitRastLine()"} @{b}Colour Functions@{ub} @{"BlankColours()" LINK "BlankColours()"} @{"ChangeColours()" LINK "ChangeColours()"} @{"ColourMorph()" LINK "ColourMorph()"} @{"ColourToPalette()" LINK "ColourToPalette()"} @{"PaletteToColour()" LINK "PaletteToColour()"} @{"PaletteMorph()" LINK "PaletteMorph()"} @{"UpdatePalette()" LINK "UpdatePalette()"} @{"UpdateColour()" LINK "UpdateColour()"} @{b}Rasterlist Functions@{ub} @{"InitRasterlist()" LINK "InitRasterlist()"} @{"HideRasterlist()" LINK "HideRasterlist()"} @{"RemoveRasterlist()" LINK "RemoveRasterlist()"} @{"ShowRasterlist()" LINK "ShowRasterlist()"} @{"UpdateRasterlist()" LINK "UpdateRasterlist()"} @{"UpdateRasterLines()" LINK "UpdateRasterLines()"} @{"UpdateRasterCommand()" LINK "UpdateRasterCommand()"} @{"UpdateRasterCommands()" LINK "UpdateRasterCommands()"} @{b}Sprite Functions@{ub} @{"InitSprite()" LINK "InitSprite()"} @{"FreeSprite()" LINK "FreeSprite()"} @{"HideSprite()" LINK "HideSprite()"} @{"HideSpriteList()" LINK "HideSpriteList()"} @{"MoveSprite()" LINK "MoveSprite()"} @{"RemoveAllSprites()" LINK "RemoveAllSprites()"} @{"ReturnAllSprites()" LINK "ReturnAllSprites()"} @{"UpdateSprite()" LINK "UpdateSprite()"} @{"UpdateSpriteList()" LINK "UpdateSpriteList()"} @EndNode --------------------------------------------------------------------------- @NODE "GameScreen" "Structure: GameScreen" NAME: GameScreen VERSION: 1 ID CODE: GS TYPE: Complex @{b}DESCRIPTION@{ub} In short, the GameScreen 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 GameScreen by passing NULL to the AddScreen() function and accepting all the user defaults (recommended whenever 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. Some functions relating to GameScreen's are: @{u}Initialisation@{uu} GetScreen() AddScreen() DeleteScreen() @{u}Actions@{uu} @{u}Manipulation@{uu} RemakeScreen() @{b}STRUCTURE@{ub} The GameScreen structure consists of the following public fields: @{"MemPtr1 " LINK GS_MemPtr1 } Pointer to screen 1 @{"MemPtr2 " LINK GS_MemPtr1 } Pointer to screen 2 (doubled buffer) @{"MemPtr3 " LINK GS_MemPtr1 } Pointer to screen 3 (tripled buffer) @{"ScreenLink " LINK GS_ScreenLink } Pointer to a linked screen. @{"Palette " LINK GS_Palette } Pointer to the screen palette. @{"Rasterlist " LINK GS_Rasterlist } Pointer to a rasterlist. @{"AmtColours " LINK GS_AmtColours } The amount of colours on screen. @{"ScrWidth " LINK GS_ScrWidth } The width of the visible screen window. @{"ScrHeight " LINK GS_ScrHeight } The height of the visible screen window. @{"PicWidth " LINK GS_PicWidth } The width of the screen picture (pixels). @{"PicByteWidth" LINK GS_PicByteWidth} The width of the screen picture (bytes). @{"PicHeight " LINK GS_PicHeight } The height of the screen picture. @{"Planes " LINK GS_Planes } The amount of planes or bits if non-planar. @{"ScrXOffset " LINK GS_ScrXOffset } Hardware co-ordinate for TOS. @{"ScrYOffset " LINK GS_ScrXOffset } Hardware co-ordinate for LOS. @{"PicXOffset " LINK GS_PicXOffset } Offset of the horizontal axis. @{"PicYOffset " LINK GS_PicXOffset } Offset of the vertical axis. @{"Attrib " LINK GS_Attrib } Special Attributes are? @{"ScrMode " LINK GS_ScrMode } What screen mode is it? @{"ScrType " LINK GS_ScrType } ILBM/Planar/Chunky8/... @{"Task " LINK GS_Task } Task that owns this screen. @{"PlaneSize " LINK GS_PlaneSize } Size of a plane (bytewidth*height) @{"Bitmap " LINK GS_Bitmap } Pointer to bitmap structure (for blitting). @EndNode --------------------------------------------------------------------------- @NODE "GS_MemPtr1" "Structure: GameScreen" @{b}FIELDS@{ub} Names: MemPtr1, MemPtr2, MemPtr3 On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite Inheritance: None. @{b}DESCRIPTION@{ub} These fields point to the screen display data. They should be NULL if you want this function to allocate the memory for you (highly recommended). Otherwise AddScreen() will assume that the values are valid pointers to video memory and will use them as such. @EndNode --------------------------------------------------------------------------- @NODE "GS_ScreenLink" "Structure: GameScreen" @{b}FIELD@{ub} Name: ScreenLink On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite Inheritance: None @{b}DESCRIPTION@{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 GameScreen structure here. @EndNode --------------------------------------------------------------------------- @NODE "GS_Palette" "Structure: GameScreen" @{b}FIELD@{ub} Name: Palette On Change: UpdatePalette(), PaletteToColour(), ColourToPalette() Structure: GameScreen Status: Read/Write Inheritance: None @{b}DESCRIPTION@{ub} Points to the palette for this screen, or NULL if you want to install a clear palette (all colours black). Your palette array must be represented in 24 bit colours (0x00RRGGBB). If the screen type is of CHUNKY15 or better, this field will be ignored as colours are represented in the pixels and not the palette. @{b}SEE ALSO@{ub} AmtColours @EndNode --------------------------------------------------------------------------- @NODE "GS_Rasterlist" "Structure: GameScreen" @{b}FIELD@{ub} Name: Rasterlist On Change: Cannot change by direct means after initialisation. Structure: GameScreen Status: Read/Write Inheritance: None @{b}DESCRIPTION@{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_AmtColours" "Structure: GameScreen" @{b}FIELD@{ub} Name: AmtColours On Change: UpdatePalette() Structure: GameScreen Status: Read/Write Inheritance: None @{b}DESCRIPTION@{ub} Specifies the amount of colours in the screen's palette. If you set this value to NULL then AddScreen() will fill it in for you, via a check to the Planes and ScrType fields. This field allows you to set colours not in use by the screen's bitmap. For example, if your screen is in 16 colours but you want to set the colours for the sprites, then you can set this value to 32 and use a 32 colour palette to set the outside values. @{b}SEE ALSO@{ub} Palette @EndNode --------------------------------------------------------------------------- @NODE "GS_ScrWidth" "Structure: GameScreen" @{b}FIELDS@{ub} Names: ScrWidth, ScrHeight On Change: RemakeScreen() Structure: GameScreen Status: Read/Write Inheritance: User default. @{b}DESCRIPTION@{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}SEE ALSO@{ub} PicWidth, PicHeight @EndNode --------------------------------------------------------------------------- @NODE "GS_PicWidth" "Structure: GameScreen" @{b}FIELDS@{ub} Names: PicWidth On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite. Inheritance: ScrWidth @{b}DESCRIPTION@{ub} Defines the picture height and width. The picture is the display data that shows through onto screen. It can be larger than the screen area, but must never be smaller than the screen area. The pixel width must be divisible by 16. If you omit the ScrType field then you are not to set the PicByteWidth value (it will be initialised from the PicWidth value). @{b}SEE ALSO@{ub} PicByteWidth, PicHeight @EndNode --------------------------------------------------------------------------- @NODE "GS_PicByteWidth" "Structure: GameScreen" @{b}FIELD@{ub} Names: PicByteWidth Synonyms: BytesPerRow, ByteWidth On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite. Inheritance: PicWidth @{b}DESCRIPTION@{ub} Defines the picture height and width. The picture is the display data that shows through onto screen. It can be larger than the screen area, but must never be smaller than the screen area. The pixel width must be divisible by 16. If you omit the ScrType field then you are not to set the PicByteWidth value (it will be initialised from the PicWidth value). @{b}SEE ALSO@{ub} PicWidth @EndNode --------------------------------------------------------------------------- @NODE "GS_PicHeight" "Structure: GameScreen" @{b}FIELDS@{ub} Names: PicHeight On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite. Inheritance: ScrHeight @{b}DESCRIPTION@{ub} Defines the picture height and width. The picture is the display data that shows through onto screen. It can be larger than the screen area, but must never be smaller than the screen area. The pixel width must be divisible by 16. If you omit the ScrType field then you are not to set the PicByteWidth value (it will be initialised from the PicWidth value). @{b}SEE ALSO@{ub} PicHeight @EndNode --------------------------------------------------------------------------- @NODE "GS_Planes" "Structure: GameScreen" @{b}FIELD@{ub} Name: Planes Synonym: BitsPerPixel On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/IWrite Inheritance: User default. @{b}DESCRIPTION@{ub} Specifies the amount of bitplanes that will be used by this screen. The amount of colours you can use is completely dependent on this value. For interleaved or planar screens you can calculate the amount of colours you get with the formula 2^n, where n is the amount of planes. If you intend to use a chunky style screen, let AddScreen() initialise the Planes field for you. @{b}SEE ALSO@{ub} ScrType @EndNode --------------------------------------------------------------------------- @NODE "GS_ScrXOffset" "Structure: GameScreen" @{b}FIELDS@{ub} Names: ScrXOffset, ScrYOffset On Change: RemakeScreen() Structure: GameScreen Status: Read/Write Inheritance: None. @{b}DESCRIPTION@{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_PicXOffset" "Structure: GameScreen" @{b}FIELDS@{ub} Names: PicXOffset, PicYOffset On Change: RemakeScreen() Structure: GameScreen Status: Read/Write Inheritance: None. @{b}DESCRIPTION@{ub} These two fields set the offsets for the picture "behind" the screen. If you want to do any sort of hardware scrolling, you will want to use these values in conjunction with MovePicture(). It is perfectly legal to preset these values before you call ShowScreen(). @EndNode --------------------------------------------------------------------------- @NODE "GS_Attrib" "Structure: GameScreen" @{b}FIELD@{ub} Name: Attrib On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/Write Inheritance: Some flags can be set by the user. @{b}DESCRIPTION@{ub} Defines the special attributes for the screen. Current available are: @{u}DBLBUFFER@{uu} Allocates an extra screen buffer which is placed in MemPtr2. See the SwapBuffers() function for more information on double buffering. @{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}PLAYFIELD@{uu} Must be set if this screen forms part of a playfield. @{u}HSCROLL@{uu} Set if you want to use horizontal picture scrolling. @{u}VSCROLL@{uu} Set if you want to use vertical picture scrolling. @{u}SBUFFER@{uu} Allocates extra space to allow you to horizontally scroll up to 50 screens in both X directions. @{u}SPRITES@{uu} Set if you intend to use sprites with this screen. @{u}BLKBDR@{uu} Turns all colours outside of the display window to black. Works on AGA only. @{u}NOSCRBDR@{uu} Allows sprites and other displayable objects to appear outside of the viewport. Works on AGA only. @{u}CENTRE@{uu} Centres the screen by calculating the correct offsets for GS_ScrXOffset and GS_ScrYOffset for any screen mode. The new settings will over-write any previous values in these fields. @{u}GETSCRMODE@{uu} Obtains the preferred user screen mode and writes it to GS_ScrMode. @EndNode --------------------------------------------------------------------------- @NODE "GS_ScrMode" "Structure: GameScreen" @{b}FIELD@{ub} Name: ScrMode On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/Write Inheritance: User default. @{b}DESCRIPTION@{ub} Defines the display mode for the screen. If you do not fill in this field, you will get the default of low 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_ScrType" "Structure: GameScreen" @{b}FIELDS@{ub} Names: ScrType On Change: Cannot change after initialisation. Structure: GameScreen Status: Read/Write Inheritance: User default. @{b}DESCRIPTION@{ub} The display data type - either PLANAR, INTERLEAVED or CHUNKY8. Descriptions of these display types are out of the scope of this autodoc, so if you require further information perhaps you should try the RKM's. Note that for planar screens the bitplanes are stored sequentially, one after the other. There is no scattering of planar bitplane memory. If you set this field to NULL then AddScreen() will initialise it to the preferred user screen type. This is exceptionally useful as some screen types are faster than others for certain effects. Also, if the screen type is unsupported directly it will have to be emulated, slowing things down dramatically. Screen type independence is strongly encouraged because of these reasons. @EndNode --------------------------------------------------------------------------- @NODE "GS_Task" "Structure: GameScreen" @{b}FIELDS@{ub} Names: Task On Change: Cannot change after initialisation. Structure: GameScreen Status: Read Only. Inheritance: Task of initialisation. @{b}DESCRIPTION@{ub} Points to a GMSTask structure that identifies the task owning this screen structure. @EndNode --------------------------------------------------------------------------- @NODE "AddScreen()" "Screens/AddScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: AddScreen() Short: Sets up a screen from given parameters. Assembler: GameScreen = AddScreen(APTR [a0]) C/C++: struct GameScreen * AddScreen(APTR GameScreen); struct GameScreen * AddScreenTags(ULONG tag, ...); @{b}@{u}DESCRIPTION@{uu}@{ub} Initialises a GameScreen structure by allocating the screen memory and making the rasterlist. A little more complex than it sounds... All GameScreens must be initialised from tag lists, or if necessary a screen structure obtained from GetScreen(). After calling this function you need to call ShowScreen() to get the screen on the display. @{b}@{u}INPUTS@{uu}@{ub} APTR - Pointer to a valid GameScreen, Taglist, List, or ObjectList. @{b}@{u}RESULT@{uu}@{ub} ErrorCode - NULL if successful. @{b}@{u}BUGS@{uu}@{ub} If you set up your screen structure incorrectly or try to do something this routine doesn't, you will run into trouble. Not all features are working even though the flags are present, but it shouldn't be too long before this function is finished. @{b}@{u}SEE ALSO@{uu}@{ub} @{"DeleteScreen" LINK "DeleteScreen()"}, @{"ShowScreen" LINK "ShowScreen()}, @{"HideDisplay" LINK "HideDisplay()}, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"} @EndNode --------------------------------------------------------------------------- @NODE "DeleteScreen()" "Screens/DeleteScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: DeleteScreen() Short: Deactivates a screen, returns memory, etc. Assembler: DeleteScreen(GameScreen [a0]) C/C++: void DeleteScreen(struct GameScreen *); @{b}@{u}DESCRIPTION@{uu}@{ub} This function will deallocate everything that was initialised when you called AddScreen(). If the screen you delete is currently active when you call this function, intution will be given back the display. If you want to get around this, initialise and display your next screen and then delete the old one. This function will clear MemPtr1, MemPtr2 and MemPtr3 in the GameScreen structure, if those fields were allocated by AddScreen(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"AddScreen" LINK "AddScreen()"}, @{"ShowScreen" LINK "ShowScreen()"} @EndNode --------------------------------------------------------------------------- @NODE "ShowScreen()" "Screens/ShowScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: ShowScreen() Short: Displays an initialised game screen. Assembler: ShowScreen(GameScreen [a0]) C/C++: void ShowScreen(struct GameScreen *); @{b}@{u}DESCRIPTION@{uu}@{ub} Displays an initialised GameScreen. A GameScreen is incompatible with intuition screens, so calling this function will result in a complete take-over of the viewport. This function makes a call to AddInputHandler() to prevent input falling through to intuition screens. It is perfectly admissable to call this function when another GameScreen is already being displayed. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"AddScreen" LINK "AddScreen()"}, @{"DeleteScreen" LINK "DeleteScreen()"} @EndNode --------------------------------------------------------------------------- @NODE "HideDisplay()" "Screens/HideDisplay" @{b}@{u}FUNCTION@{uu}@{ub} Name: HideDisplay() Short: Hides the GMS display from view. Assembler: GameScreen = HideDisplay() C/C++: struct GameScreen * HideDisplay(void); @{b}@{u}DESCRIPTION@{uu}@{ub} This function is private and is for internal use only. This function will hides the GMS display from view. This will cause the OS viewport to be returned, but GMS will still be running "in the background". If GMS is not running on top of another OS then the GMS WorkBench screen will be displayed and the calling task will be put to the back. If no GMS screen is displayed then this function does nothing, and returns a NULL value. @{b}@{u}RESULT@{uu}@{ub} GameScreen - Points to the structure of the GameScreen that has been hidden by this function. Otherwise NULL if no GameScreen was active. @{b}@{u}SEE ALSO@{uu}@{ub} @{"ShowScreen" LINK "ShowScreen()"} @EndNode --------------------------------------------------------------------------- @NODE "SwapBuffers()" "Screens/SwapBuffers" @{b}@{u}FUNCTION@{uu}@{ub} Name: SwapBuffers Short: Switch the screen display buffers. Assembler: SwapBuffers(GameScreen [a0]) C/C++: void SwapBuffers(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Swaps GS_MemPtr1 and GS_MemPtr2, and activates the new bitmap for the display. If triple buffered, then all three MemPtr's are switched. Visually: @{b}BEFORE AFTER@{ub} MemPtr1 MemPtr2 MemPtr2 ----> MemPtr3 MemPtr3 MemPtr1 You can get the addresses contained in these values, but you must never physically change these pointers yourself. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @EndNode --------------------------------------------------------------------------- @NODE "RemakeScreen()" "Screens/RemakeScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: RemakeScreen() Short: Remakes the screen display according to its size, width, and position on the monitor. Assembler: RemakeScreen(GameScreen [a0]) C/C++: void RemakeScreen(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Remakes the GameScreen's display @{i}window@{ui} as quickly as possible. If the GameScreen is hidden then the changes will show up the next time you call ShowScreen(). You cannot change the display mode, screen type or amount of screen colours with this function. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @EndNode --------------------------------------------------------------------------- @NODE "MovePicture()" "Screens/MovePicture" @{b}@{u}FUNCTION@{uu}@{ub} Name: MovePicture() Short: Moves the screen to specified X/Y values. Assembler: MovePicture(GameScreen [a0]) C/C++: void MovePicture(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} This routine has two uses: Moving the picture to any position on the display, and for Hardware Scrolling. It will take the values from PicXOffset and PicYOffset in the GameScreen structure and use them to set the new picture position. This function will execute at the same speed for all offset values. You must have set the HSCROLL bit for horizontal scrolling and the VSCROLL bit for vertical scrolling if you wish to use this function. If you set the HBUFFER flag in ScrAttrib then you can also use this function to legally hardware-scroll up to 50 screens in either X direction. Do not draw graphics beyond these boundaries as you will damage the system. @{b}NOTES@{ub} If the graphics hardware does not support hardware scrolling, this routine will probably blit the entire picture to the new position. This is very slow but is the only other option. The normal execution time for this function on ECS/AGA is 2/3rds of a single rasterline on an A1200+Fast. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. The PicXOffset and PicYOffset values will be used to set the picture's new on-screen position. @{b}@{u}SEE ALSO@{uu}@{ub} @{"ResetPicture" LINK "ResetPicture()"} @EndNode --------------------------------------------------------------------------- @NODE "ResetPicture()" "Screens/ResetPicture" @{b}@{u}FUNCTION@{uu}@{ub} Name: ResetPicture() Short: Resets the picture position to position 0X, 0Y. Assembler: ResetPicture(GameScreen [a0]) C/C++: void ResetPicture(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Resets the picture position to 0X, 0Y. This method is faster than clearing the PicXOffset and PicYOffset fields and then calling MovePicture(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}RESULT@{uu}@{ub} PicXOffset and PicYOffset in the GameScreen will be cleared. @{b}@{u}SEE ALSO@{uu}@{ub} @{"MovePicture" LINK "MovePicture()"} @EndNode ----------------------------------------- ---------------------------------- @NODE "ColourMorph()" "Screens/ColourMorph" @{b}@{u}FUNCTION@{uu}@{ub} Name: ColourMorph() Short: Fades a of set of colours into one colour value. Assembler: FadeState = ColourMorph(GameScreen [a0], FadeState [d0], Speed [d1], StartColour [d3], AmtColours [d4], SrcColour [d2], DestColour [d5]) C/C++: UWORD ColourMorph(struct GameScreen *, UWORD FadeState, UWORD Speed, ULONG StartColour, ULONG AmtColours, ULONG SrcColour, ULONG DestColour) @{b}@{u}DESCRIPTION@{uu}@{ub} Fades the screen from one colour into another colour. Once you call this function, you have to keep on calling it until it gives you a result of NULL. This allows you to put this function in a loop and do other things while the fade is active. This function uses the proportional fading algorithm to acheive its effect. @{b}@{u}NOTE@{uu}@{ub} All fading functions ignore the colour values that are kept internally. This will cause problems for you if you do not know what your current palette looks like when using these functions. @{b}@{u}EXAMPLE@{uu}@{ub} FadeState = NULL; do { WaitVBL(); FadeState = ColourMorph(GameScreen,FadeState,1,0,32,0xFF00AA,0xA7BC30); } while (FadeState != NULL) @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. FadeState - Initialise to zero, then keep sending the returned value back until you get a NULL in this field. Speed - The required speed for the fade. SrcColour - The colour that you are fading from, 0xRRGGBB format. DestColour - The colour that you are fading to, 0xRRGGBB format. StartColour - The colour to start fading from (0 ... AmtColours-1). AmtColours - The amount of colours to fade (1 ... MaximumColours). You must never use a value of 0 here. @{b}@{u}RESULT@{uu}@{ub} FadeState - Returns NULL if the fade has finished. @{b}@{u}SEE ALSO@{uu}@{ub} @{"PaletteToColour" LINK "PaletteToColour()"}, @{"PaletteMorph" LINK "PaletteMorph()"}, @{"ColourToPalette" LINK "ColourToPalette()"} @EndNode --------------------------------------------------------------------------- @NODE "ColourToPalette()" "Screens/ColourToPalette" @{b}@{u}FUNCTION@{uu}@{ub} Name: ColourToPalette() Short: Fades a set of colours into a range of values. Assembler: FadeState = ColourToPalette(GameScreen [a0], FadeState [d0], Speed [d1], StartColour [d3], AmtColours [d4], Palette [a1], Colour [d2]) C/C++: UWORD ColourToPalette(struct GameScreen *, UWORD FadeState, UWORD Speed, UWORD StartColour, UWORD AmtColours, APTR Palette, ULONG Colour) @{b}@{u}DESCRIPTION@{uu}@{ub} Fades a set of colours of the same value, into a range of colours specified in Palette. Once you call this function, you have to keep on calling it until it gives you a result of NULL. This allows you to put this function in a loop and do other things while the fade is active. This function uses the proportional fading algorithm to acheive its effect. @{b}@{u}NOTE@{uu}@{ub} All fading functions ignore the colour values that are kept internally. This will cause problems for you if you do not know what your current palette looks like when using these functions. Keep track of your current palette values to help you with functions like PaletteMorph(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. FadeState - Initialise to zero, then keep sending the returned value back until you get a NULL in this field. Speed - The required speed for the fade. Palette - Pointer to the palette used as the source. Colour - The colour that you are fading from, 0xRRGGBB format. StartColour - The colour to start fading from (0 ... AmtColours-1). AmtColours - The amount of colours to fade (1 ... MaximumColours). You must never use a value of 0 here. @{b}@{u}RESULT@{uu}@{ub} FadeState - Returns NULL if the fade has finished. @{b}@{u}SEE ALSO@{uu}@{ub} @{"PaletteMorph" LINK "PaletteMorph()"}, @{"ColourToPalette" LINK "ColourToPalette()"}, @{"ColourMorph" LINK "ColourMorph()"} @EndNode --------------------------------------------------------------------------- @NODE "PaletteMorph()" "Screens/PaletteMorph" @{b}@{u}FUNCTION@{uu}@{ub} Name: PaletteMorph() Short: Fades a set of colours into a new set of values. Assembler: FadeState = PaletteMorph(GameScreen [a0], FadeState [d0], Speed [d1], StartColour [d3], AmtColours [d4], SrcPalette [a1], DestPalette [a2]) C/C++: UWORD PaletteMorph(struct GameScreen *, UWORD FadeState, UWORD Speed, UWORD StartColour, UWORD AmtColours, APTR SrcPalette, APTR DestPalette) @{b}@{u}DESCRIPTION@{uu}@{ub} This function will take the palette in SrcPalette, and use it to fade a colour set into the palette given in DestPalette. Once you call this function, you have to keep on calling it until it gives you a result of NULL. This allows you to put this function in a loop and do other things while the fade is active. This function uses the proportional fading algorithm to acheive its effect. @{b}@{u}NOTE@{uu}@{ub} All fading functions ignore the colour values that are kept internally. This will cause problems for you if you do not know what your current palette looks like when using these functions. Keep track of your palette's values and point to them in SrcPalette if you find that this problem is occurring for you. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. FadeState - Initialise to zero, then keep sending the returned value back until you get a NULL in this field. Speed - The required speed for the fade. SrcPalette - Pointer to the palette used as the source. Destpalette - Pointer to the palette that you want to fade to. StartColour - The colour to start fading from (0 ... AmtColours-1). AmtColours - The amount of colours to fade (1 ... MaximumColours). You must never use a value of 0 here. @{b}@{u}RESULT@{uu}@{ub} FadeState - Returns NULL if the fade has finished. @{b}@{u}SEE ALSO@{uu}@{ub} @{"ColourToPalette" LINK "ColourToPalette()"}, @{"PaletteToColour" LINK "PaletteToColour()"}, @{"ColourMorph" LINK "ColourMorph()"} @EndNode --------------------------------------------------------------------------- @NODE "PaletteToColour()" "Screens/PaletteToColour" @{b}@{u}FUNCTION@{uu}@{ub} Name: PaletteToColour() Short: Fades a set of colours into a specific colour value. Assembler: FadeState = PaletteToColour(GameScreen [a0], FadeState [d0], Speed [d1], StartColour [d3], AmtColours [d4], Palette [a1], Colour [d2]) C/C++: UWORD PaletteToColour(struct GameScreen *, UWORD FadeState, UWORD Speed, ULONG StartColour, ULONG AmtColours, APTR Palette, ULONG Colour) @{b}@{u}DESCRIPTION@{uu}@{ub} This function will fade a set of various colour values into a single colour value. This is useful for fading the screen to black for example. Once you call this function, you have to keep on calling it until it gives you a result of NULL. This allows you to put this function in a loop and do other things while the fade is active. This function uses the proportional fading algorithm to acheive its effect. @{b}@{u}NOTE@{uu}@{ub} All fading functions ignore the colour values that are kept internally. This will cause problems for you if you do not know what your current palette looks like when using these functions. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. FadeState - Initialise to zero, then keep sending the returned value back until you get a NULL in this field. Speed - The required speed for the fade. Palette - Pointer to the palette used as the source. Colour - The colour you want to fade to, in 0xRRGGBB format. StartColour - The colour to start fading from (0 ... AmtColours-1). AmtColours - The amount of colours to fade (1 ... MaximumColours). You must never use a value of 0 here. @{b}@{u}RESULT@{uu}@{ub} FadeState - Returns NULL if the fade has finished. @{b}@{u}SEE ALSO@{uu}@{ub} @{"PaletteMorph" LINK "PaletteMorph()"}, @{"PaletteToColour" LINK "PaletteToColour()"}, @{"ColourMorph" LINK "ColourMorph()"} @EndNode --------------------------------------------------------------------------- @NODE "ChangeColours()" "Screens/ChangeColours" @{b}@{u}FUNCTION@{uu}@{ub} Name: ChangeColours() Short: Change a set of colours in a GameScreen's internal palette. Assembler: ChangeColours(GameScreen [a0], Colours [a1], StartColour [d0], AmtColours [d1]) C/C++: void ChangeColours(struct GameScreen *, APTR Colours, ULONG StartColour, ULONG AmtColours). @{b}@{u}DESCRIPTION@{uu}@{ub} Changes all colours within the set range. Alterations will only be made to the screen's internal palette. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Colours - Pointer to a list of 24 bit colours. StartColour - The first colour to be affected by the change. NB: The first colour is defined as 0. AmtColours - The amount of colours to be affected by the change. Must be at least 1. @EndNode --------------------------------------------------------------------------- @NODE "BlankColours()" "Screens/BlankColours" @{b}@{u}FUNCTION@{uu}@{ub} Name: BlankColours() Short: Drives all screen colours to zero (black). Assembler: BlankColours(GameScreen [a0]) C/C++: void BlankColours(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Drives all the colours to zero, which should give a black screen. You won't be able to see any picture detail after calling this routine. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @EndNode --------------------------------------------------------------------------- @NODE "UpdatePalette()" "Screens/UpdatePalette" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdatePalette() Short: Updates an entire GameScreen palette to new colour values. Assembler: UpdatePalette(GameScreen [a0]) C/C++: void UpdatePalette(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates an entire GameScreen palette to new colour values, as pointed to in the GS_Palette field. If GS_Palette is NULL then all of the screens colours will be turned black. This function has no effect on true colour screens. @{b}@{u}NOTE@{uu}@{ub} Palette changes will appear when the next vertical blank occurs. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"UpdateColour" LINK "UpdateColour()"} @EndNode --------------------------------------------------------------------------- @NODE "UpdateColour()" "Screens/UpdateColour" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateColour() Short: Updates a 24 bit $RRGGBB colour value. Assembler: UpdateColour(GameScreen [a0], Colour [d0], RRGGBB [d1]) C/C++: void UpdateRGB(struct GameScreen *, ULONG Colour, ULONG RRGGBB) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates a single colour value in the screen's palette. The change is immediately visible following the next vertical blank. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Colour - The colour number to update, between 0 and GameScreen->AmtColours. RRGGBB - Colour value in standard RRGGBB format. @{b}@{u}SEE ALSO@{uu}@{ub} @{"UpdatePalette" LINK "UpdatePalette()"} @EndNode --------------------------------------------------------------------------- @NODE "InitRasterlist()" "Screens/InitRasterlist" @{b}@{u}FUNCTION@{uu}@{ub} Name: InitRasterlist() Short: Initialise a new rasterlist. Assembler: ErrorCode = InitRasterlist(GameScreen [a0]) C/C++: UWORD InitRasterlist(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Initialises a new rasterlist in a GameScreen structure. A rasterlist is a group of commands executed at specific areas of the display. On current Amiga's, rasterlists are executed by the copper (copperlist's) at preset lines on the screen. When you call this function a copperlist will be set up according to the commands you give in your rasterlist structure. In the past creating copperlists was a major compatibility concern because you need to pass the copper direct hardware addresses. Thankfully with GMS this is no longer such a problem. There is still the issue of gfx boards not having a copper style chip on them. Luckily many of these commands can in some way be emulated, so all is not lost on that front. Current valid commands are: @{u}WAITLINE @{uu} Waits for the vertical beam to reach the specified screen position. It is perfectly legal to enter numbers that go outside of your screen's vertical limits (ie negative numbers and numbers greater than the screen height), but no more than a value of 10. Note that the purpose of this command is to specify the screen position at which the next command will be executed. All line values must be specified in lo-res pixels, regardless of your screen resolution. @{u}COLOUR ,@{uu} Changes a 24 bit colour value to another. @{u}COLOURLIST ,,,@{uu} Allows you to generate the classic coloured lines used by games and demos everywhere. This command is mostly useful for sky/background effects, although you could probably use it for all sorts of things. @{u}SPRITE @{uu} Re-activates a sprite bank at the specified line. This is commonly known as sprite-splitting. This function is considered "dangerous" and may simply do nothing on many gfx boards (although emulation is a certain possibility). @{u}REPOINT @{uu} Repoints the screen bitmap to another area in chip ram, causing a screen split at the point that this command is executed. @{u}SCROLL @{uu} Alters the scroll position of a bitplane to within 16 pixels. This is really only useful for scrolling parallax landscapes. @{u}FSCROLL ,@{uu} Alters the scroll position of a bitplane to within 16 + 4 quarter pixels. This is really only useful for scrolling parallax landscapes. @{u}FLOOD@{uu} A special effect that reverses the bitplane modulo, causing the bitplane to repeat itself. This effect is used as a novel way of "fading in" the screen. @{u}MIRROR@{uu} Similar to Flood, but does a complete reversal of the modulo so that the bitplane is "flipped over". See examples/AGAMirror.s to see how this works. @{u}RASTEND@{uu} You must terminate your rasterlist with this command. [If you have any other ideas for commands, mail me. - Paul] @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. GS_Rasterlist in this structure must contain a pointer to a standard rasterlist. Look at the examples in this package to help you with designing your rasterlists. @{b}@{u}RESULT@{uu}@{ub} ErrorCode - Is NULL if the initialisation was successful. Otherwise it will return one of the following values: ERR_NOMEM = Not enough memory was available for one of the allocations. ERR_NOPTR = You didn't put an address pointer in GS_Rasterlist. ERR_INUSE = A rasterlist is still in use by this screen (remove the old one). @{b}@{u}SEE ALSO@{uu}@{ub} UpdateRasterlist, ShowRasterlist, HideRasterlist, RemoveRasterlist, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"} @EndNode --------------------------------------------------------------------------- @NODE "UpdateRasterlist()" "Screens/UpdateRasterlist" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateRasterlist() Short: Update an existing rasterlist. Assembler: UpdateRasterlist(GameScreen [a0]) C/C++: void UpdateRasterlist(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Completely updates a rasterlist's commands and waitline's to whatever values GS_Rasterlist may now hold. The length of time to do this depends on how big your rasterlist is (generally, it will do the update very fast though). Make sure that any changes are within the limits of your original values, for example you cannot make changes to the amount of colours used in a NEWPALETTE command. If you only want to update the lines or the command datas, then you can call UpdateRastCommands() or UpdateRastLines(), which can be a bit faster in certain situations. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} InitRasterlist, ShowRasterlist, HideRasterlist, RemoveRasterlist, UpdateRastCommands, UpdateRastLines, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"} @EndNode --------------------------------------------------------------------------- @NODE "UpdateRasterLines()" "Screens/UpdateRasterLines" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateRasterLines() Short: Updates all the WaitLine's in an active rasterlist. Assembler: void UpdateRasterLines(GameScreen [a0]) C/C++: void UpdateRasterLines(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates every occurance of a WAITLINE command in an active rasterlist. This includes the update of waitline's within commands such as COLOURLIST. All other commands are excluded from being updated by this function. This function has been provided because for other functions it can be unsafe to update single WAITLINE commands. Whenever you want one or more raster line's updated we insist that you use this or the UpdateRasterlist() routine. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} UpdateRasterCommand, UpdateRasterCommands, UpdateRasterlist @EndNode --------------------------------------------------------------------------- @NODE "UpdateRasterCommand()" "Screens/UpdateRasterCommand" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateRasterCommand() Short: Update a single rasterlist command. Assembler: UpdateRasterCommand(GameScreen [a0], Command [a2]) C/C++: void UpdateRasterCommand(struct GameScreen *, APTR Command) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates a single raster command. This is the fastest way to update any single command in a rasterlist. For the update of multiple commands, use UpdateRasterlist() or UpdateRasterCommands(). You must never use this command to update changes in WAITLINE commands. Doing so can have unpredictable effects on other line related commands on screen. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Command - Points to the rasterlist command to be updated. @{b}@{u}SEE ALSO@{uu}@{ub} UpdateRasterCommands, UpdateRasterLines, UpdateRasterlist @EndNode --------------------------------------------------------------------------- @NODE "UpdateRasterCommands()" "Screens/UpdateRasterCommands" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateRasterCommands() Short: Update a group of rasterlist commands. Assembler: UpdateRasterCommands(GameScreen [a0], Command [a2], Amount [d0]) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates a group of raster commands in a screen's active rasterlist. This is the fastest way to update a group of commands without having to do a complete rasterlist update. If you only want to update a single command, use UpdateRasterCommand(). For all the commands, use UpdateRasterlist(). You must never use this command to update changes in WAITLINE commands. Doing so can have unpredictable effects on other line related commands on screen. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Command - Points to the first rasterlist command to be updated. Amount - The amount of commands to be updated. @{b}@{u}SEE ALSO@{uu}@{ub} UpdateRasterCommand, UpdateRasterLines, UpdateRasterlist @EndNode --------------------------------------------------------------------------- @NODE "RemoveRasterlist()" "Screens/RemoveRasterlist" @{b}@{u}FUNCTION@{uu}@{ub} Name: RemoveRasterlist() Short: Hide and delete Rasterlist from memory. Assembler: RemoveRasterlist(GameScreen [a0]) C/C++: void RemoveRasterlist(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Removes the memory used by the rasterlist's internal setup. If the rasterlist is currently displayed then it will be hidden from the view before the deletion. Once this function is called the rasterlist is gone - if you want to redisplay your rasterlist, you must reinitialise it with a call to InitRasterlist(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} InitRasterlist, ShowRasterlist, HideRasterlist, RemoveRasterlist, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"} @EndNode --------------------------------------------------------------------------- @NODE "HideRasterlist()" "Screens/HideRasterlist" @{b}@{u}FUNCTION@{uu}@{ub} Name: HideRasterlist() Short: Hide a rasterlist from the display. Assembler: HideRasterlist(GameScreen [a0]) C/C++: void HideRasterlist(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Hides a rasterlist from the screen display. This function does not delete the internal rasterlist or change the GameScreen structure in any way. You can return the list to the display simply by calling ShowRasterlist(). @{b}@{u}NOTE@{uu}@{ub} There is a VBL delay in this function so that the rasterlist is not removed while the beam is still executing its instructions. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} InitRasterlist, RemoveRasterlist, ShowRasterlist, HideRasterlist, UpdateRasterlist @EndNode --------------------------------------------------------------------------- @NODE "ShowRasterlist()" "Screens/ShowRasterlist" @{b}@{u}FUNCTION@{uu}@{ub} Name: ShowRasterlist() Short: Display a rasterlist on screen. Assembler: ShowRasterlist(GameScreen [a0]) C/C++: void ShowRasterlist(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Display a rasterlist on the screen. The pointer to the rasterlist must lie in GS_Rasterlist, and must have been initialised by a call to InitRasterlist(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} InitRasterlist, HideRasterlist, ShowRasterlist, RemoveRasterlist, UpdateRasterlist @EndNode --------------------------------------------------------------------------- @NODE "InitSprite()" "Screens/InitSprite" @{b}@{u}FUNCTION@{uu}@{ub} Name: InitSprite() Short: Initialise a sprite structure. Assembler: Sprite = InitSprite(GameScreen [a0], Sprite [a1]) C/C++: struct Sprite * InitSprite(struct GameScreen *, struct Sprite *) @{b}@{u}DESCRIPTION@{uu}@{ub} Initialises a sprite ready for placement on the screen. After calling this function you can use sprite functions such as UpdateSprite(), MoveSprite() etc. If it is impossible to show the sprite, then an error code will be returned. In such a case it helps to have a blitter routine as back up, so that you can instead display the sprite as a BOB on screen. Sprites are very much dependent on the machine hardware, so be aware that the image may not show on some machines. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Sprite - A sprite structure or tag list. Here follows a description of each Sprite field: @{u}Number@{uu} The bank number that this sprite is going to use. @{u}Data@{uu} Points to the beginning of the sprite data (starts with the two control words). @{u}XCoord@{uu} Defines the horizontal position of the sprite when displayed. Negative or extreme values that put the sprite outside of the screen are permitted. @{u}YCoord@{uu} Defines the vertical position of the sprite when displayed. Negative or extreme values that put the sprite outside of the screen are permitted. @{u}Frame@{uu} The number of the frame to display. The first frame is 0, the last frame is defined by the amount of following graphics for the sprite. @{u}Width@{uu} The width of the sprite in pixels. Under OCS/ECS the only available range is 16 pixels. Under AGA this is extended by permission of values 32 and 64. @{u}Height@{uu} The height of the sprite in pixels. A valid range is between 0 and 256. @{u}AmtColours@{uu} The amount of colours used by this sprite. This will be either 4 colours or 16 colours if the sprite is to work on OCS/ECS/AGA. @{u}ColStart@{uu} The colour bank at which the colours are going to start for this sprite. This value goes up in increments of 16, eg 0,16,32,48... Under OCS/ECS you must set this value to 16. For AGA the maximum limit is 240. Note that under current hardware conditions, all sprites must share the same colour bank. Do not attempt to set a different colour bank for each individual sprite. @{u}Planes@{uu} Specifies the amount of planes used per bank. Set this value to 2. @{u}Resolution@{uu} Defines the display mode for the sprite. Possible flags are: LORES - Puts the sprite in low resolution. (Default) HIRES - Specifies a high resolution sprite. SHIRES - Specifies a super-high resolution sprite. XLONG - Use this flag if you want to join two sprites together on the X axis. The second sprite's data must follow the first sprite and fit the same attributes. @{u}FieldPriority@{uu} Defines the position of the sprite in relation to the screen playfields. If set to 0 then the sprite is at the very front, if set to 1 then the sprite is one field behind, and so on. @{b}@{u}SEE ALSO@{uu}@{ub} MoveSprite, UpdateSprite, UpdateSpriteList, HideSpriteList, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"} @EndNode --------------------------------------------------------------------------- @NODE "UpdateSprite()" "Screens/UpdateSprite" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateSprite() Short: Place a sprite on the screen. Assembler: UpdateSprite(GameScreen [a0], Sprite [a1]) C/C++: void UpdateSprite(struct GameScreen *, struct Sprite *) @{b}@{u}DESCRIPTION@{uu}@{ub} Updates the sprite co-ordinates (screen location) and recalculates the sprite image pointers for animation. This function cannot make sudden changes to the width, colours, resolution, or height of the sprite. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Sprite - Pointer to an initialised Sprite structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"InitSprite" LINK "InitSprite()"}, @{"MoveSprite" LINK "MoveSprite()"} @EndNode --------------------------------------------------------------------------- @NODE "MoveSprite()" "Screens/MoveSprite" @{b}@{u}FUNCTION@{uu}@{ub} Name: MoveSprite() Short: Move a sprite to a new screen location. Assembler: MoveSprite(GameScreen [a0], Sprite [a1]) C/C++: void MoveSprite(struct GameScreen *, struct Sprite *) @{b}@{u}DESCRIPTION@{uu}@{ub} Moves a sprite to a new screen location according to the X and Y co-ordinates found SPR_XCoord and SPR_YCoord in the Sprite structure. This function does not act on any other Sprite fields and is intended for use with non-animated sprites. @{b}NOTES@{ub} On graphics hardware where sprites are not supported, the sprite may be drawn to screen as a BOB. There is no list support as static sprites are a rarity in games. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Sprite - Pointer to an initialised Sprite structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"InitSprite" LINK "InitSprite()"}, @{"UpdateSprite" LINK "UpdateSprite()"} @EndNode --------------------------------------------------------------------------- @NODE "HideSprite()" "Screens/HideSprite" @{b}@{u}FUNCTION@{uu}@{ub} Name: HideSprite() Short: Remove a sprite from the screen display. Assembler: HideSprite(GameScreen [a0], Sprite [a1]) C/C++: void HideSprite(struct GameScreen *, struct Sprite *) @{b}@{u}DESCRIPTION@{uu}@{ub} Hides a sprite from the screen display. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. Sprite - Pointer to an initialised Sprite structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"HideSpriteList" LINK "HideSpriteList()"} @EndNode --------------------------------------------------------------------------- @NODE "UpdateSpriteList()" "Screens/UpdateSpriteList" @{b}@{u}FUNCTION@{uu}@{ub} Name: UpdateSpriteList() Short: Update a list of initialised sprites. Assembler: UpdateSpriteList(GameScreen [a0], SpriteList [a1]) C/C++: void UpdateSpriteList(struct GameScreen *, APTR SpriteList) @{b}@{u}DESCRIPTION@{uu}@{ub} Update a series of initialised sprites according to a SpriteList. This function is provided as an alternative to making constant calls to UpdateSprite(), which can be quite time consuming. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. SpriteList - Pointer to a SpriteList containing a list of up to 8 initialised sprites. The list must be terminated by a LISTEND, eg: SpriteList: dc.l "LIST" dc.l Sprite1 dc.l Sprite2 dc.l Sprite3 dc.l Sprite4 dc.l LISTEND @{b}@{u}SEE ALSO@{uu}@{ub} @{"UpdateSprite" LINK "UpdateSprite()"} @EndNode --------------------------------------------------------------------------- @NODE "HideSpriteList()" "Screens/HideSpriteList" @{b}@{u}FUNCTION@{uu}@{ub} Name: HideSpriteList() Short: Hide sprites as specified by a SpriteList. Assembler: HideSpriteList(GameScreen [a0], SpriteList [a1]) C/C++: void HideSpriteList(struct GameScreen *, APTR SpriteList) @{b}@{u}DESCRIPTION@{uu}@{ub} Hide a series of currently displayed sprites from the screen. This function is provided as an alternative to making constant calls to HideSprite(), which can be quite time consuming. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. SpriteList - Pointer to a SpriteList containing a list of up to 8 initialised sprites. The list must be terminated by a LISTEND, eg: SpriteList: dc.l "LIST" dc.l Sprite1 dc.l Sprite2 dc.l Sprite3 dc.l Sprite4 dc.l LISTEND @{b}@{u}SEE ALSO@{uu}@{ub} @{"HideSprite" LINK "HideSprite()"} @EndNode --------------------------------------------------------------------------- @NODE "RemoveAllSprites()" "Screens/RemoveAllSprites" @{b}@{u}FUNCTION@{uu}@{ub} Name: RemoveAllSprites() Short: Remove all sprites from the display. Assembler: RemoveAllSprites(GameScreen [a0]) C/C++: void RemoveAllSprites(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Removes all displayed sprites from the screen simply by altering the DMA Controller. This is the fastest way to remove all sprites from the display quickly and easily. @{b}@{u}NOTE@{uu}@{ub} After you have called this function you cannot see any visible changes to sprites until you call ReturnAllSprites(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"ReturnAllSprites" LINK "ReturnAllSprites()"} @EndNode --------------------------------------------------------------------------- @NODE "ReturnAllSprites()" "Screens/ReturnAllSprites" @{b}@{u}FUNCTION@{uu}@{ub} Name: ReturnAllSprites() Short: Return all sprites to the display. Assembler: ReturnAllSprites(GameScreen [a0]) C/C++: void ReturnAllSprites(struct GameScreen *) @{b}@{u}DESCRIPTION@{uu}@{ub} Returns all sprites that were previously removed by RemoveAll- Sprites(). @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"RemoveAllSprites" LINK "RemoveAllSPrites()"} @EndNode --------------------------------------------------------------------------- @NODE "AllocVideoMem()" "Screens/AllocVideoMem" @{b}@{u}FUNCTION@{uu}@{ub} Name: AllocVideoMem() Short: Allocate blitter memory. Assembler: Memory = AllocVideoMem(Size [d0], Flags [d1]) C/C++: APTR AllocVideoMem(ULONG Size) @{b}@{u}DESCRIPTION@{uu}@{ub} Allocates a block of memory suitable for the video display. This type of memory is also compatible with the Blitter.GPI, and should continue to do so for all hardware configurations. The memory will be tracked as outlined in AllocMemBlock() if resource tracking is turned on. @{b}@{u}INPUTS@{uu}@{ub} Size - The Size of the memory to allocate. @{b}@{u}RESULT@{uu}@{ub} Memory - Pointer to the allocated memory. All video memory is formatted with 0's when allocated. Returns NULL if error. @{b}@{u}SEE ALSO@{uu}@{ub} @{"FreeMemBlock" LINK "GMSAutodoc.guide/FreeMemBlock()"} @EndNode --------------------------------------------------------------------------- @NODE "WaitVBL()" "Screens/WaitVBL" @{b}@{u}FUNCTION@{uu}@{ub} Name: WaitVBL() Short: Waits for a vertical blank. Assembler: WaitVBL() C/C++: void WaitVBL(void); @{b}@{u}DESCRIPTION@{uu}@{ub} Waits until the horizontal beam reaches the Vertical BLank area. This routine will try and give you as much VBL space as possible, usually by waiting for the exact point where the display stops. If this is not possible, then it will wait for the beam to reach the top of the monitor display. This function has an implanted AutoSwitch() call to make screen switching very easy to implement. @{b}@{u}SEE ALSO@{uu}@{ub} @{"WaitRastLine" LINK "WaitRastLine()"} @EndNode --------------------------------------------------------------------------- @NODE "WaitRastLine()" "Screens/WaitRastLine" @{b}@{u}FUNCTION@{uu}@{ub} Name: WaitRastLine() Short: Waits for the strobe to reach a specific line. Assembler: WaitRastLine(LineNumber [d0]) C/C++: void WaitRastLine(WORD LineNumber) @{b}@{u}DESCRIPTION@{uu}@{ub} Waits for the strobe to reach the scan-line specified in LineNumber. The recognised range is dependent on the low resolution height of your screen, eg 0-255 for a standard 320x256 screen. It is permissable to enter negative values and values that exceed this range, but only do so if absolutely necessary. This function has been specially written to avoid beam misses caused by the untimely activation of interrupts. @{b}@{u}INPUTS@{uu}@{ub} LineNumber - Vertical beam position to wait for. @{b}@{u}BUGS@{uu}@{ub} If you enter a large value that is well beyond the range limit, like #350, the strobe will never reach this line because line 350 doesn't even exist. This will cause your program to lock up. Please keep your values restricted to the height of your screen. @{b}@{u}SEE ALSO@{uu}@{ub} @{"WaitVBL" LINK "WaitVBL()"} @EndNode --------------------------------------------------------------------------- @NODE "BlankOn()" "Screens/BlankOn" @{b}@{u}FUNCTION@{uu}@{ub} Name: BlankOn() Short: Blanks out the entire display until BlankOff() is called. Assembler: BlankOn() C/C++: void BlankOn(void) @{b}@{u}DESCRIPTION@{uu}@{ub} After calling this function the screen display will be completely blanked out until BlankOff() is called. For the duration that the display is blanked out, there will be no visible screen effects whatsoever. Note that ShowScreen() is completely incapable of ending a screen blanking period, but once the screen display is returned any screen alterations will be visible. This function is intended for making a clean transition between two screens, ie closing one screen then opening another. @{b}@{u}SEE ALSO@{uu}@{ub} @{"BlankOff" LINK "BlankOff()"} @EndNode --------------------------------------------------------------------------- @NODE "BlankOff()" "Screens/BlankOff" @{b}@{u}FUNCTION@{uu}@{ub} Name: BlankOff() Short: Gives back the display after BlankOn() was called. Assembler: BlankOff() C/C++: void BlankOff(void) @{b}@{u}DESCRIPTION@{uu}@{ub} This function returns the screen display after calling BlankOn(). Any hidden visual changes that occurred after the BlankOn() call will become immediately visible after calling this function. @{b}@{u}SEE ALSO@{uu}@{ub} @{"BlankOn" LINK "BlankOn()"} @EndNode --------------------------------------------------------------------------- @NODE "FreeSprite()" "Screens/FreeSprite" @{b}@{u}FUNCTION@{uu}@{ub} Name: FreeSprite() Short: Frees a sprite from the system. Assembler: FreeSprite(Sprite [a1]) C/C++: void FreeSprite(struct Sprite *); @{b}@{u}DESCRIPTION@{uu}@{ub} Frees a previously initialised sprite from the system. This function has garbage protection and will safely ignore sprites that have not actually been initialised. @{b}@{u}INPUT@{uu}@{ub} Sprite - Pointer to an initialised sprite structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"InitSprite" LINK "InitSprite()"} @EndNode --------------------------------------------------------------------------- @NODE "GetScreen()" "Screens/GetScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: GetScreen() Short: Gets the latest version of the GameScreen structure. Assembler: GameScreen = GetScreen() C/C++: struct GameScreen * GetScreen(void) @{b}@{u}DESCRIPTION@{uu}@{ub} Allocates the latest version of a GMS GameScreen structure and returns it back to you. The structure fields will be empty so that you can fill them out to suit your requirements. Before your program exits you will need to free the structure, this is automatically done in the DeleteScreen() function. You have to use this function if you do not want to use tag lists to initialise your GameScreen (remember that it is illegal to compile and use pre-initialised structures in GMS programs). @{b}@{u}RESULT@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"AddScreen" LINK "AddScreen()"} @EndNode --------------------------------------------------------------------------- @NODE "TakeDisplay()" "Screens/TakeDisplay" @{b}@{u}FUNCTION@{uu}@{ub} Name: TakeDisplay() Short: Private function. Assembler: ErrorCode = TakeDisplay(GameScreen [a0]) C/C++: ULONG TakeDisplay(struct GameScreen *); @{b}@{u}DESCRIPTION@{uu}@{ub} Takes the display from the Operating System that GMS is running on. This is a special function in the monitor drivers, and is reserved for use in the Screens GPI. @{b}@{u}INPUTS@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}RESULT@{uu}@{ub} ErrorCode - Returns ERR_OK if successful. @{b}@{u}SEE ALSO@{uu}@{ub} @{"ReturnDisplay" LINK "ReturnDisplay"} @EndNode --------------------------------------------------------------------------- @NODE "ReturnDisplay()" "Screens/ReturnDisplay" @{b}@{u}FUNCTION@{uu}@{ub} Name: ReturnDisplay() Short: Private function. Assembler: GameScreen = ReturnDisplay(); C/C++: struct GameScreen * ReturnDisplay(); @{b}@{u}DESCRIPTION@{uu}@{ub} Returns the monitor display to the OS that GMS is running on. This is a special function in the monitor drivers, and is reserved for use in the Screens GPI. @{b}@{u}RESULT@{uu}@{ub} GameScreen - Pointer to the GameScreen that was removed. @{b}@{u}SEE ALSO@{uu}@{ub} @{"TakeDisplay" LINK "TakeDisplay"} @EndNode --------------------------------------------------------------------------- @NODE "FreeVideoMem()" "Screens/FreeVideoMem" @{b}@{u}FUNCTION@{uu}@{ub} Name: FreeVideoMem() Short: Frees a memory block allocated from FreeVideoMem(). Assembler: FreeVideoMem(MemBlock) C/C++: void FreeVideoMem(APTR MemBlock); @{b}@{u}DESCRIPTION@{uu}@{ub} Frees a memory block allocated from AllocVideoMem(). @{b}@{u}INPUT@{uu}@{ub} MemBlock - The memory block to be freed. @{b}@{u}SEE ALSO@{uu}@{ub} @{"AllocVideoMem" LINK "AllocVideoMem()"}, @{"AllocMemBlock" LINK "AllocMemBlock()"} @EndNode --------------------------------------------------------------------------- @NODE "GetScrType()" "Screens/GetScrType" @{b}@{u}FUNCTION@{uu}@{ub} Name: GetScrType() Short: Gets the default/user screen type. Assembler: ScrType = GetScrType() C/C++: ULONG GetScrType(void); @{b}@{u}DESCRIPTION@{uu}@{ub} Returns the screen type that is being used as the default in the Screens GPI. This function is often used by other GPI's, since the ScrType is a common field in structures not initialised by the Screens GPI. @{b}@{u}RESULT@{uu}@{ub} ScrType - The default screen type (eg PLANAR). @EndNode --------------------------------------------------------------------------- @NODE "RefreshScreen()" "Screens/RefreshScreen" @{b}@{u}FUNCTION@{uu}@{ub} Name: RefreshScreen() Short: Updates the screen display. Assembler: RefreshScreen(GameScreen [a0]) C/C++: void RefreshScreen(struct GameScreen *); @{b}@{u}DESCRIPTION@{uu}@{ub} @{b}@{u}INPUT@{uu}@{ub} GameScreen - Pointer to an initialised GameScreen structure. @{b}@{u}SEE ALSO@{uu}@{ub} @{"WaitVBL" LINK "WaitVBL()"} @EndNode --------------------------------------------------------------------------- @NODE "()" "Screens/" @{b}@{u}FUNCTION@{uu}@{ub} @{b}SYNOPSIS@{ub} @{b}@{u}DESCRIPTION@{uu}@{ub} @{b}@{u}INPUTS@{uu}@{ub} @{b}@{u}RESULT@{uu}@{ub} @{b}@{u}SEE ALSO@{uu}@{ub} @EndNode