Graphic Segments

=Flushing strategies= 
//Rod Bird//
[[toc]]
----
==Intro== 
Flush is a command that perplexes quite a few folks. I hope to clarify its use and help you choose the most appropriate drawing and flushing strategy for your project. The Help File is very clearly worded, as you read this document refresh your mind on each of the noted graphics commands.

The main purpose of flush is to preserve the drawn graphics so that they may be redrawn, should the program window be minimized or covered by another window. If the graphics have not been flushed you will be looking at a blank white window when it is restored or uncovered.

For the more adventurous, flush allows multiple graphic scenes to be flicked on and off screen.

==The drawing history past and present== 
Liberty drawing commands do more than paint pixels on the screen, the drawing commands you issue are recorded in memory. The commands are recorded sequentially and grouped together in SEGMENTS. You form a segment by issuing a FLUSH command. Realize that this recording is always on. From the moment the program starts and immediately after a flush command, a new CURRENT SEGMENT is in play.

Flushed segments are the past, only they will be restored if the screen is minimized or covered by another window. The current segment is the present, current segment drawing will be lost unless flushed into the past or preserved in another way.

==Naming and numbering== 
Segments are identified by an ever increasing number. The first segment created will be numbered 1, the next 2 and so on. If we delete segments it makes no difference, the next segment will be numbered one higher than the last. Liberty allows us to establish the number of a segment and store that in an appropriate program variable by issuing a SEGMENT variablename command. Even more conveniently it allows us to store the number directly to a system variable with a SEGMENT name command.

The one thing that catches most folks out is that flush saves the segment but also immediately establishes a new segment. If you obtain the segment number before you flush then you have the number of the flushed segment, if you obtain it after the flush you have actually obtained the number of the new current segment. Simply deduct one in that situation.

==Managing segments== 
Segments can be deleted with DELSEGMENT (name), redrawn individually with REDRAW (name) or all undeleted segments redrawn with the command, REDRAW.

REDRAW (name) will paint the named segment to the front of the screen, this changes the Z order of the drawing on screen. REDRAW will appear to restore the Z order and paint undeleted segments in their original Z order.

You can erase all segments by issuing a CLS command. This deletes all flushed segments, the current segment and wipes the screen. You can clear the current segment by issuing a DISCARD command.

==Decouple the screen and drawing history== 
Only the redraw and cls command have any impact on what you see on the screen, other commands act only on the segments held in memory. Delsegment (name) will have no impact on the screen, discard will have no impact on the screen but the segment (name) will be deleted and the current segment will be wiped clean. Decouple the screen and the drawing history in your mind.

==Manage memory== 
It is important to manage segments as they consume memory. Even if you don’t use flush it is important to manage the current segment memory with discard.

==Start with a clean sheet== 
When you start, start with a clean sheet, use DISCARD. Think what is in your current segment, think what you have flushed already . You might use CLS if you wanted to start completely fresh.

[[image:scr1.png]][[image:mu1.png]]Memory use is zero and there are no forgotten drawing commands.

[[code format="vbnet"]]format="lb"]]
    'good practice to start with a clean sheet
    #1.gb "cls"
    'or
    #1.gb "discard"
[[code]]


==Static graphics== 
If you are painting graphics that will not be changed, say a Company logo then simply draw and flush once.

[[image:scr2.png]][[image:mu1.png]]Memory use is managed to one segment.

[[code format="vbnet"]]format="lb"]]
    'this is the static graphic example
    nomainwin
    WindowWidth  = 600
    WindowHeight = 400
    UpperLeftX   = (DisplayWidth-WindowWidth)/2
    UpperLeftY   = (DisplayHeight-WindowHeight)/2
    graphicbox #1.gb, 50,25,500,300
    open "Static Graphic Example" for window_nf as #1
    #1 "trapclose [quit]"

    'put the pen down and set the font
    'note cls has no impact on these settings
    #1.gb "down ; font comic_sans 48"

    'good practice to start with a clean sheet
    #1.gb "cls"

    'draw my static graphics
    #1.gb "fill cyan ; backcolor red ; color red"
    #1.gb "place 100 50 ; boxfilled  300 150"
    #1.gb "place 300 150 ; circlefilled 100"
    #1.gb "backcolor cyan ; color red"
    #1.gb "place 50 100 ;\1"

    'now flush the graphics once and once only
    #1.gb "flush"
    wait

    'click on the title bar of the windows and
    'slide the window off screen and back,
    'the graphics are retained. Rem out the
    'flush command and try again.

    [quit]
    close #1
    end
[[code]]


==Refreshed graphics== 
If you are painting fresh graphics, that completely replace the previous graphics, then you must DELSEGMENT the previous segment prior to drawing and flushing the next. That way there is only ever one segment in memory. This is a task that can get folks tied in knots. If you find that your program runs out of memory it is probably because you are not obtaining the correct segment number to delete.

[[image:scr8.png]][[image:mu1.png]]Memory use is managed to one segment.

[[code format="vbnet"]]format="lb"]]
    'this is the refreshed graphic example, only one segment
    'is ever retained in memory.
    nomainwin
    WindowWidth  = 600
    WindowHeight = 400
    UpperLeftX   = (DisplayWidth-WindowWidth)/2
    UpperLeftY   = (DisplayHeight-WindowHeight)/2
    button #1.b, "Draw Graphic", [nextdrawing], UL, 250, 340
    textbox #1.tb 350, 340, 100, 25
    graphicbox #1.gb, 50,25,500,300
    open "Refreshed Graphic Example" for window_nf as #1
    #1 "trapclose [quit]"

    'put the pen down and set the font
    'note cls has no impact on these settings
    #1.gb "down ; font comic_sans 48"

    'good practice to start with a clean sheet
    #1.gb "cls"

    drawing=1
    wait

    [nextdrawing]
    'first delete the last segment, it does not matter that
    'first time round this loop there isn't a segment to delete
    'Liberty will ignore the command
    #1.gb "delsegment seg"

    'now paint over the last graphics on screen
    if drawing=1 then 'draw graphics 1
        #1.gb "fill pink ; backcolor red ; color red"
        #1.gb "place 100 50 ; boxfilled  300 150"
        #1.gb "place 300 150 ; circlefilled 100"
        #1.gb "backcolor pink"
        #1.gb "place 50 100 ;\1"
    end if
    if drawing=2 then 'draw graphics 2
        #1.gb "fill yellow ; backcolor green ; color green"
        #1.gb "place 300 50 ; boxfilled  400 200"
        #1.gb "place 300 200 ; circlefilled 100"
        #1.gb "backcolor yellow"
        #1.gb "place 250 50 ;\2"
    end if
    if drawing=3 then 'draw graphics 3
        #1.gb "fill cyan ; backcolor yellow ; color yellow"
        #1.gb "place 100 200 ; boxfilled  350 250"
        #1.gb "place 100 200 ; circlefilled 50"
        #1.gb "place 350 200 ; circlefilled 50"
        #1.gb "backcolor cyan ; color yellow"
        #1.gb "place 200 170 ;\3"
    end if

    drawing=drawing+1
    if drawing=4 then drawing=1

    'now flush the graphics and store the segment
    'number in the variable seg
    #1.gb "flush seg"

    'The seg variable is catching the segment id and will
    'increase everytime through the loop

    'print the segment id number for info
    'note the name variable "seg" is for internal use.

    'to obtain and use the segment number in a variable
    'of your own, use segment variablename
    'this will provide the current segment number,
    'deduct one to get the true number of the last
    'flushed segment.
    #1.gb "segment currentsegmentnumber"
    lastflushed=currentsegmentnumber-1
    #1.tb "Seg ID:";lastflushed
    wait

    [quit]
    close #1
    end
[[code]]



==Animated graphics== 
If you are painting animated graphics by overdrawing and redrawing repetitively you must manage memory and repetitively DISCARD the current segment. The screen will behave as you expect but unless you DISCARD the current segment history memory use will build.

[[image:scr3.png]][[image:mu1.png]]Memory use is minimal.

==Background and foreground graphics== 
If you are going to have a mostly static background and some constantly changing foreground graphics, say sliders or dials then draw the background, FLUSH that as the first segment. You will retain that segment. Now draw and FLUSH the foreground segment. Next time through DELSEGMENT the foreground segment REDRAW the background and then draw and FLUSH the new foreground.

[[image:scr4.png]][[image:mu1.png]]Memory use will not exceed two segments.

==Multiple segment graphics== 
If you want to get fancy you can maintain several segments in memory and change the order they appear on screen. Now most often this strategy will use partial or transparent graphics. By that I mean they will fill only parts of the screen. If you use Fills they will cover graphics behind. The segments are maintained in memory in the Z order they were created. They can be pulled to the front of the screen with REDRAW (name). And appear to change the Z order on screen. If the segment has a full screen fill in it, all graphics will be hidden when that segment is redrawn. You might choose to do this and have a background segment, in this way you can hide and show any segments you wish.

[[image:scr5.png]][[image:scr6.png]][[image:scr7.png]][[image:mu2.png]]Memory use builds depending on segments used.