ROWS

RISC OS Widget Set

Rather crappy documentation

Abstraction layer

This file documents in brief the ROWS GUI abstraction layer. At the time of writing, this isn't complete (ROWS_window is still in need of a bit of a fix), however, the observant of you will have noticed that now only the ROWS_X* source files reference X library functions, and ROWS_drawable, etc run a little bit slower than before.

The abstraction layer is currently described in ROWSint_drawable.h. To start writing a graphics driver for ROWS, you first need to derive a new drawable widget from the base widget (you could probably derive a new drawable from one of the non-abstract drawables, but you will need to be cautious about trampling over some of the data structures). As I write this, there's still quite a lot of crap lying around in the source code from my first attempt at the same thing...

Anyway, back to your new drawable. In your setup function, you need to call ROWS_drawable_get_abstraction_layer() (defined in ROWSint_drawable.h) to get a pointer to the structure that holds the functions. Note that you can only change this in your setup function - if you try altering the functions from anywhere else, you risk thread-safeness problems. The function returns a pointer to a ROWS_drawable_brush_calls structure, which currently contains one item - 'functions', which is an array of all the functions (which have some default values). Each of these functions is of type void foo(ROWS_drawable_fparam *param). The ROWS_drawable_fparam structure is defined in ROWSint_drawable.h, and is used to pass the parameters to the various functions. These parameters are passed as follows:

• Colour functions
  ROWS_drawable_fparam.colour.*
  ROWS_drawable_fparam.colour.colour (the ROWS_colour structure itself)
  • ROWS_DRAWABLE_COLOUR_CREATE - ROWS_drawable_fparam.colour.data.create
• Brush functions
  ROWS_drawable_fparam.brush.*
  ROWS_drawable_fparam.brush.brush (the ROWS_brush widget)
  • ROWS_DRAWABLE_BRUSH_CREATE
  • ROWS_DRAWABLE_BRUSH_DESTROY
  • ROWS_DRAWABLE_BRUSH_SET_GC
  • ROWS_DRAWABLE_BRUSH_USE_PRIVATE_GC
  • ROWS_DRAWABLE_BRUSH_SET_LINEWIDTH
    ROWS_drawable_fparam.brush.data.singleint.value (new line width)
  • ROWS_DRAWABLE_BRUSH_SET_FGCOLOUR
    ROWS_drawable_fparam.brush.data.colour
  • ROWS_DRAWABLE_BRUSH_SET_BGCOLOUR
    ROWS_drawable_fparam.brush.data.colour
  • ROWS_DRAWABLE_BRUSH_GET_FGPIXEL
    ROWS_drawable_fparam.brush.data.singleint.value (change on exit to foreground pixel value)
  • ROWS_DRAWABLE_BRUSH_DRAW_POINT
    ROWS_drawable_fparam.brush.data.coordinate
  • ROWS_DRAWABLE_BRUSH_DRAW_LINE
    ROWS_drawable_fparam.brush.data.line
  • ROWS_DRAWABLE_BRUSH_DRAW_ARC
    ROWS_drawable_fparam.brush.data.arc
  • ROWS_DRAWABLE_BRUSH_DRAW_RECTANGLE
    ROWS_drawable_fparam.brush.data.line (x2,y2 are the width and height)
  • ROWS_DRAWABLE_BRUSH_FILL_ARC
    ROWS_drawable_fparam.brush.data.arc
  • ROWS_DRAWABLE_BRUSH_FILL_RECTANGLE
    ROWS_drawable_fparam.brush.data.line (x2,y2 are the width and height)
• And so on and so forth...

Generally you will want to store additional data with each brush that is created for your drawable. ROWSint_brush.h contains the ROWS_brush widget data structure. _p_ROWS_brush_data.data is of particular interest, as you can use it to store any data you like (at least if your drawable is directly derived from ROWS_drawable). Use ROWS_alloc to allocate the data (as it produces an error on failure) in your function for ROWS_DRAWABLE_BRUSH_CREATE. The other items in the ROWS_brush structure can be pretty much used how you like, although it's probably best to keep to their default definitions:

• use_private_gc - nonzero if this brush should use its own GC (which isn't applicable for all graphics devices - just ignore the value if your device doesn't support this feature)
• last_serial - the last clipping rectangle serial number - you can use this to see if someone has changed the clipping rectangle/region of this brush's drawable.
• colour - the ROWS_colour this brush should be drawing in
• drawable - the drawable this brush should be drawing on

You may be intrigued to know the meaning of the last_serial. Well, the ROWS_drawable data structure is also open to perusal by your driver (although I recommend that you only read from it [I could provide a function layer to go through to read from it, but that would be slow...]). You can check if the _p_ROWS_drawable_data.clip_serial is equal to your brush's last_serial number (_p_ROWS_drawable_data.clip_serial is automatically updated by the ROWS_drawable_* functions when required, and you don't have to worry about doing this yourself in your abstraction layer).

Anyway, I think that's about it... Note that, with the exception of ROWS_DRAWABLE_BRUSH_CREATE & DESTROY, the functions default to an error message, and that generally the drawable is not locked on entrance to the colour and brush functions and you might need to lock it yourself with ROWS_widget_lock.

Not finished