occam-pi powered

Valid CSS!

Valid XHTML 1.1!

Last modified 14th January 2006
This document is maintained by Fred Barnes
Department of Computer Science, University of Kent.

occam-pi SDL Raster Graphics

This page documents the "SDLRaster" library in KRoC, for providing basic framebuffer-oriented graphics using the SDL (simple direct-media layer) library.

[ SDLRaster | events | control | examples ]

SDLRaster

The SDLRaster library included with the latest versions of KRoC (1.4.0-final and above) provides a simple frame-buffer for occam-pi programs, represented as a 2D mobile array of INTs. The library does not yet support the whole wealth of SDL operations -- only basic framebuffers.

The following basic routines are provided:

The provided RASTER type is defined as:


    DATA TYPE RASTER IS MOBILE [][]INT:
		

The buffers communicated and represented using this type are 2D arrays of integers, with each integer representing a single pixel. Since both SDLRaster and DXRaster are intended for 24 or 32-bit displays (that most are these days), the integers that make up the pixels have 8-bits of red, green and blue. If specifying hexidecimal constants for pixel values, the makeup is: #00ggrrbb (on my system anyway -- it should be fairly obvious if your system does things differently). If an integer is treated as a [4]BYTE array, the bytes will be in reverse (e.g. red in pixel[1], green in pixel[2] and blue in pixel[0]).

Because the RASTER type uses dynamic mobile arrays, when a process outputs one, it is gone from that process (i.e. may not be referenced again). The mobiles communicated by the SDLRaster process must not intermix with application data of the same type; neither should an application attempt to create these rasters or free them. The rasters come out of the SDLRaster process and should go back there :-).

Events

The various events delivered from SDLRaster are sent as SDLEVENT records, defined as:


    DATA TYPE SDLEVENT
      RECORD
        INT type:
        INT data:
    :
		

The type field contains the event (constants defined in sdlraster.inc), the data field contains any event-specific data. These are defined as:

event numberdescriptionevent data
EVENT.UNKNOWNunknown or unsupported eventundefined
EVENT.EXPOSEexpose event (raster obscured and redrawn)undefined
EVENT.BUTTON.PRESSmouse button pressedbutton data: ((x /\ #FFF) << 20) \/ ((y /\ #FFF) << 8) \/ ((key.state /\ #F) << 4) \/ (button /\ #F)
EVENT.BUTTON.RELEASEmouse button releasedbutton data: ((x /\ #FFF) << 20) \/ ((y /\ #FFF) << 8) \/ ((key.state /\ #F) << 4) \/ (button /\ #F)
EVENT.KEY.PRESSkey pressedkey data: (unicode-char /\ #FFFF)
EVENT.KEY.RELEASEkey releasedkey data: (unicode-char /\ #FFFF)
EVENT.QUITuser closing windowundefined
EVENT.MOTIONmouse motionmotion data: ((x /\ #FFF) << 20) \/ ((y /\ #FFF) << 8) \/ ((key.state /\ #F) << 4) \/ (button-state /\ #F)
EVENT.CKEY.PRESScontrol-key pressedcontrol-key (see below)
EVENT.CKEY.RELEASEcontrol-key releasedcontrol-key (see below)

The various control keys currently recognised are:

control-keydescription
CKEY.UNKNOWNunknown control key
CKEY.BACKSPACEbackspace
CKEY.NUMLOCKnum-lock
CKEY.CAPSLOCKcaps-lock
CKEY.SCROLLOCKscroll-lock
CKEY.RSHIFTright-shift
CKEY.LSHIFTleft-shift
CKEY.RCTRLright-control
CKEY.LCTRLleft-control
CKEY.RALTright-alt
CKEY.LALTleft-alt
CKEY.RMETAright-meta
CKEY.LMETAleft-meta
CKEY.RSUPERright-super (windows key)
CKEY.LSUPERleft-super (windows key)
CKEY.SYSREQsys-rq key
CKEY.MENUmenu key (windows key)
CKEY.MODEmode switch (alt-gr)
CKEY.UPup
CKEY.DOWNdown
CKEY.LEFTleft
CKEY.RIGHTright
CKEY.HOMEhome
CKEY.ENDend
CKEY.PAGEUPpage-up
CKEY.PAGEDOWNpage-down
CKEY.INSERTinsert
CKEY.DELETEdelete

To extract the X/Y/button-state/key-state data from events the following functions are provided:

Control messages

The control messages currently supported (sent as a single integer) are:

control constantdescription
CTL.SHUTDOWNshut-down the raster

Examples

A number of basic example programs are provided in the KRoC distribution, in the "sdlraster/examples/" sub-directory. To build these, use "./build examples" in the KRoC source tree (or from 1.4.0-pre2 onwards, "./build sdlraster_examples"). In a binary distribution, pre-built SDLRaster examples (if supported) will be installed in PREFIX/share/kroc/examples/sdlraster.

The SDLRaster code no longer uses user-defined channels (it uses CIF instead). As such, the 'gridlink' process has been removed, making SDLRaster somewhat nicer to work with. The following shows a basic application outline for using SDLRaster:


    #INCLUDE "sdlraster.inc"
    #USE "sdlraster"
    #USE "course.lib"

    PROC test (CHAN BYTE screen!)
      CHAN RASTER c, d:
      CHAN SDLEVENT events:
      CHAN INT control:
      PAR
      	SDLRaster ("test", 320, 200, 1, d?, c!, events!, control?)
	SDLRasterAutoClose (events?, control!)

        RASTER r:
        SEQ
          out.string ("hello from SDLRaster test :)*n", 0, screen!)
          c ? r                         -- get raster
          WHILE TRUE
            SEQ
              ...  scribble on r
              SDLRasterUpdate (r)
              ...  do suitable delay
          d ! r                         -- return raster (bit redundant here)
    :
		

Which would be compiled with:


    bash$ kroc mytest.occ -lcourse -lsdlraster -lSDL -lcif
		

Copyright © 2005-2006, Fred Barnes, Department of Computer Science, University of Kent.