Documentation for graphex.ew v0.10.0
Table of Contents

0_StartHere

The graphex.ew system is generalised buffered drawing system on top of win32lib.


A 'gfx' is an offscreen Pixmap buffer that knows its position within the window it is created in, can handle events with a shadow Bitmap control and maintains a system for drawing only what is needed during a w32HPaint event.

The paint handler gfx_paint is installed automatically when you create a new gfx object with newGfx. You can also add other handlers, eg w32HMouse, w32HKeyPress etc with gfxAttachHandler.

In this way you can create simple graphics inside a win32lib program which are self contained and essentially look after themselves.

Although one of the demo programs is a game, you will see that it is a very retro style game and graphex.ew is not really a game programming library. I added the functions like gfxSpriteOverlap because it was easy to do so in the system I had already created.

Likewise the text drawing capability ( see Font ) uses crude line fonts (only one at present) and is not intended to be pretty, just functional.

Since you can easily get a handle on the offscreen Pixmap you can do anything you like with that Pixmap that you can do with win32lib. Beware though that I don't yet know how this will affect the painting routines.

This system was written to fulfil a basic need and turned into a way for me to learn more about how win32lib does things and about Windows painting methods themselves.

Worth noting is that originally I drew on dibs with Tommy Carlier's win32dib.ew system not really realising what that system is best used for. It turned out to be too slow for what I wanted to do (which is a shame, because a slightly blurred output of line drawings looks really cool) and was implemented with just dibPutPixel and my own line and circle drawing functions (hence the line drawing font).
So because of that, I believe this system could be implemented on any graphics system that supports drawing primitives and events (eg like SDL). I used to see pictures of line drawn games (like demo_asteroid.exw) in computing magazines back in the 80's when of course most games were using bitmapped sprites in order to reduce the needed computing power. So this system is also in a way my homage to the illustrators of those early computing books who created such great looking games in a world where the reality was very much different :-)

But I digress. The main concepts here are:
  • A gfx is an abstracted double buffered graphical pseudo control
  • They are created with newGfx
  • All drawing is done with the gfx_draw procedure
  • Clear with gfxClear
  • Draw shapes (or sprites) with gfx_draw(gfx, "shape", colour, {sprite_data})
  • or draw lines, ellipses, rectangles, etc
  • Draw basic text with gfxTextOutAt

    A note on "Sprites" or "Shapes". A Shape is what something looks like and a Sprite is a Shape with a starting location. More properly, it should have other Information attached as well, like the asteroids in demo3-asteroid.exw.

  • proc gfxAttachHandler(gfx, eventType, routine_id)   Attach a handler for an event to the gfx
  • proc gfxClear(gfx, colour)   Clears a gfx to the specified colour
  • proc gfxDestroy(gfx)   Destroy a gfx when you are finished with it
  • func gfxScaleShape(shape_data, scale)   Scales a shape in size
  • proc gfx_draw(gfx, primitive_type, colour, points)   The main generalised drawing procedure
  • func newGfx(parent_id, at_x, at_y, width, height)   Creates a new gfx object

    Documentation for graphex.ew v0.10.0
    Table of Contents

    [proc]
    gfxAttachHandler
    (gfx, eventType, routine_id)

    Attach a handler for an event to the gfx

    Category: 0_StartHere

    Use this to attach other handlers, eg for w32HMouse, or w32HKeyPress etc.
    The handler is attached to the shadow Bitmap object as it seemed to me at the time that Pixmaps don't receive events.

    See Also: gfxClear, gfxDestroy, gfxScaleShape, gfx_draw, newGfx


    Documentation for graphex.ew v0.10.0
    Table of Contents

    [proc]
    gfxClear
    (gfx, colour)

    Clears a gfx to the specified colour

    Category: 0_StartHere

    colour can be any colour win32lib can handle
    gfx can be an integer to the index of the gfx (TODO gfxIndex) or an actual gfx.
    You can also pass -1 for the gfx to clear all known gfx objects.

    See Also: gfxAttachHandler, gfxDestroy, gfxScaleShape, gfx_draw, newGfx


    Documentation for graphex.ew v0.10.0
    Table of Contents

    [proc]
    gfxDestroy
    (gfx)

    Destroy a gfx when you are finished with it

    Category: 0_StartHere

    Destroys all controls associated with the gfx and removes it from the global gfxs sequence

    See Also: gfxAttachHandler, gfxClear, gfxScaleShape, gfx_draw, newGfx


    Documentation for graphex.ew v0.10.0
    Table of Contents

    [func]
    gfxScaleShape
    (shape_data, scale)

    Scales a shape in size

    Category: 0_StartHere

    This function scales a shape and returns the scaled shape.
    Although it can accept a fractional scale it works best with integers as scaling the types of shapes this system uses results in integer roundings which alter the intent of the original shape. Just try it and see :)

    See Also: gfxAttachHandler, gfxClear, gfxDestroy, gfx_draw, newGfx


    Documentation for graphex.ew v0.10.0
    Table of Contents

    [proc]
    gfx_draw
    (gfx, primitive_type, colour, points)

    The main generalised drawing procedure

    Category: 0_StartHere

    This is the gateway to drawing on the gfx.
    It takes the gfx you want to draw on, the type of primitive you want to draw the colour and a sequence appropriate for the primitive type. The primitive type is a string description, eg "line", "ellipse", etc. And will eventually mirror the types of primitive that win32lib has to offer.

    Primitive types:
    "rect-solid" - points is {x1, y1, x2, y2} - draws a solid rectangle in colour
    "rect" - points is {x1, y1, x2, y2} - draws a rectangle outline in colour
    "line" - points is {x1, y1, x2, y2} - draws a line in colour from x1,y1 to x2,y2
    "ellipse" - points is {x1, y1, x2, y2} - draws an ellipse outline in colour bounded by x1,x2,y1,y2
    "ellipse-solid" - points is {x1, y1, x2, y2} - draws a solid ellipse
    "shape" - points is {x1, y1, {delta_x, delta_y, pen_status}, ...}
    A shape starts at x1, y1 and moves through the remaining deltas either drawing a line or not depending on pen_status True or False.
    "shape-test" is like "shape" but uses two colours for colour in the form {colour1, colour2}. If the Pen is Up then it uses colour1, if it is down it uses colour2. The reason this is here is for demo2-shapes.exw and allows drawing of the shape in a away that shows the different pen status of each segment. the generalised drawing procedure

    See Also: gfxAttachHandler, gfxClear, gfxDestroy, gfxScaleShape, newGfx


    Documentation for graphex.ew v0.10.0
    Table of Contents

    [func]
    newGfx
    (parent_id, at_x, at_y, width, height)

    Creates a new gfx object

    Returns: The gfx sequence. You can pass this to other functions, it is not very big.

    Category: 0_StartHere

    This function handles creating all the background things needed for double buffered drawing within win32lib. Once you have a gfx object you can draw things on it.
    gfx_draw handles most of the drawing (though you can use gfxBuf to get a handle to the offscreen buffer to draw what you want).

    parent_id is the control that the gfx is created in. It will usually be a win32lib id from creating a window.
    at_x, at_y is the point within the parent_id the gfx will display
    width, height is the size, in pixels, of the gfx object

    If you have called setGfxAutoPaint as true then anything you draw will automatically be drawn. Otherwise when all the drawing is done call doGfxPaint and all your drawing in that cycle will be rendered on screen.
    Note that when you create a new gfx you probably won't see it on screen because it will be the same colour as the window's default background colour. Call gfxClear to clear it to a different colour.

    See Also: gfxAttachHandler, gfxClear, gfxDestroy, gfxScaleShape, gfx_draw