====== ugBASIC User Manual ======

===== SCREENS =====

This section explains how ugBASIC screens are created and made ready to display the wonders of text, graphics and special effects. Whenever an ugBASIC program is run, a screen area is automatically set up to display the results of that program. This is known as the "default" screen, and it forms the standard display area that is used for all normal drawing and text operations. 

==== Bitmap vs tilemap ====

Screens can be used in two different ways. 

The first mode, the fastest on some architecture, is to consider the screen as made of a limited set of tiles (normally ''TILE WIDTH'' x ''TILE HEIGHT'' pixels each). This mode is called ''TILEMAP'' mode and in this mode individual "dots" are equal to each tile. Obviously, you can [[:midres_bitmap|use special crafted tilesets]], and draw up to 16 independent dots for each characters. However, ugBASIC will work as each tile is the single unit that can be addressed using the various commands.

     REM functional style
     native = BIT( SCREEN, TILEMAP )
     
     IF native THEN
        PRINT "TILEMAP IS NATIVE"
     ELSE
        PRINT "TILEMAP IS EMULATED"
     ENDIF
     
     REM declarative style
     native = BIT TILEMAP OF SCREEN
     
     IF native THEN
        PRINT "TILEMAP IS NATIVE"
     ELSE
        PRINT "TILEMAP IS EMULATED"
     ENDIF
     
     REM conditional style
     IF SCREEN HAS BIT TILEMAP THEN
        PRINT "TILEMAP IS NATIVE"
     ELSE
        PRINT "TILEMAP IS EMULATED"
     ENDIF
     
     IF SCREEN IS TEXT THEN
        PRINT "TILEMAP IS NATIVE"
     ELSE
        PRINT "TILEMAP IS EMULATED"
     ENDIF
 
The second mode is the ''BITMAP'' one, where you can address each dot on the screen (called "pixels"). This is the slowest mode but it is the more precise way to draw on the screen. In this mode, ugBASIC will work as each pixel is the single unit that can be addressed.

     REM functional style
     native = BIT( SCREEN, BITMAP )
     
     IF native THEN
        PRINT "BITMAP IS NATIVE"
     ELSE
        PRINT "BITMAP IS EMULATED"
     ENDIF
      
     REM declarative style
     native = BIT BITMAP OF SCREEN
     
     IF native THEN
        PRINT "BITMAP IS NATIVE"
     ELSE
        PRINT "BITMAP IS EMULATED"
     ENDIF
   
     REM conditional style
     IF SCREEN HAS BIT BITMAP THEN
        PRINT "BITMAP IS NATIVE"
     ELSE
        PRINT "BITMAP IS EMULATED"
     ENDIF
   
     IF SCREEN IS BITMAP THEN
        PRINT "BITMAP IS NATIVE"
     ELSE
        PRINT "BITMAP IS EMULATED"
     ENDIF
   
You can switch modes by calling commands ''BITMAP ENABLE'' or ''TILEMAP ENABLE''.

    BITMAP ENABLE
    WAIT 2000 MS
    TILEMAP ENABLE

==== Screen resolution and colors ====

Given the great variety of hardware that ugBASIC supports and the isomorphic approach adopted, the commands to set the resolution, color depth and other characteristics have been made as hardware independent as possible. In this regard, the following approach has been adopted. It is possible to ask for specific chacteristics, such as height and width of the screen. However ugBASIC will choose the closest resolution, based on the hardware on which it will runs. Likewise, if no type of resolution constraint is set, the best is offered.

To change resolution and colors, you can use the ''(W,H,C)'', ''(W,C)'' or the ''(C)'' syntax after ''BITMAP ENABLE'' or the ''TILE ENABLE'' command. The ''W'' letter is the width requested, the ''H'' letter is the height requested and, finally, the ''C''' is the number of colors requested. If you omit a parameters, it means that it is not important to set.

Here you are some examples:

    BITMAP ENABLE (320,200,16): REM at least 320x200 pixels, with 16 colors
    BITMAP ENABLE (320,,4): REM at least 320 pixels of width, with 4 colors
    BITMAP ENABLE (,256,2): REM at least 256 pixels of height, with 2 colors
    BITMAP ENABLE (320,200): REM at least 320x200 pixels, with any number of colors
    BITMAP ENABLE (320,): REM at least 320 pixels of width, with any number of colors
    BITMAP ENABLE (): REM it is equivalent to BITMAP ENABLE
    BITMAP ENABLE (,): REM it is equivalent to BITMAP ENABLE
    BITMAP ENABLE (,,): REM it is equivalent to BITMAP ENABLE
    
    TILEMAP ENABLE (40,25,16)
    TILEMAP ENABLE (32,,2)

To obtain the effective width and height of the screen, you can use ''SCREEN WIDTH'' and ''SCREEN HEIGHT'', as well as the ''COLOR COUNT''.

     BITMAP ENABLE (320,200): REM we are uninterested on the number of colors
     REM retrieve the real resolution (in pixel)
     w = SCREEN WIDTH: h = SCREEN HEIGHT: c = COLOR COUNT
     TILEMAP ENABLE
     REM retrieve the real resolution (in characters)
     w = SCREEN WIDTH: h = SCREEN HEIGHT: c = COLOR COUNT
     
==== Clearing a screen ====

The ''CLS'' command erases all or part of the current screen. When the screen is in ''BITMAP'' mode, the contents of the current screen are deleted and the background color is replaced by the current paper colour. If the screen is in ''TILEMAP'' mode, the content is replaced by using the ''EMPTY TILE'', as previously defined. Otherwise, the equivalent value for the pixel 0 is used.

    BITMAP ENABLE (320,200,16)
    PAPER RED
    CLS
    WAIT 2000 MS
    TILEMAP ENABLE
    PAPER YELLOW
    EMPTY TILE = 65
    CLS

By specifying the index number of a particular colour after the CLS command, the clearing operation will be carried out using that colour. 

    BITMAP ENABLE (320,200,16)
    PAPER RED
    CLS WHITE