|
This part of the guide contains detailed descriptions of the
BUSH built-in packages.
4.18 Pen Package
NOTE: This package is under construction. The features have not been finalized.
The pen package is the BUSH drawing environment. It is based on the
Simple DirectMedia Layer portable drawing environment originally created
by Loki Games, a Linux games company. However, the SDL is strictly a
hardware interface: it contains few drawing primitives. The pen package
extends the SDL for useful drawing.
The drawing surface is called a canvas. The canvas can be a window or
the hardware screen, but it can also be an off-screen area in memory. The
drawing area is divided up into a number of rectangular pixels.
To open a new canvas in a X Windows window, use:
=> pen.new_window_canvas( 256, 256, 16, canvas_id )
=> (Assuming canvas_id is a new pen.canvas_id variable)
=> pen.set_title( canvas_id, "Drawing Area" )
This canvas will be 256 pixels wide, 256 pixels high, a minimum of 16-bit colour and
it will have an X windows title of "Drawing Area". canvas_id is the id number referring
to the canvas.
The coordinate system of the canvas has an origin point at the top-left
corner of the drawing surface. The coordinate lines actually fall between
the pixels so that coordinate (0,0) is actually to the upper-left of the
first pixel. The coordinates are floating point numbers representing a
percentage of the canvas. The canvas ranges from (0,0) to (100,100).
The pen package draws on the canvas using an imaginary pen. The pen
has several properties:
- Position - the location of the pen on the canvas
- Direction - the angle of rotation of the pen
- Ink - the solid colour used drawing with the pencil brush
- Pattern - multi-colour ink used for drawing
- Brush - how the ink is spread on the canvas
- Mode - how the ink is combined with the canvas pixels
Pen modes include:
- Off - the pen moves but no drawing takes place
- Copy - the ink overwrites the existing pixels on the canvas. This
is the normal pen mode.
- Invert - the ink is exclusive-or'd with the pixels. Where the
ink is 0%, the canvas is unchanged. Where the ink is 100%, the canvas pixels
are transformed to the opposite colour. This is useful for simple hilighting
that doesn't lose information on the canvas.
- Add - adds the canvas pixels to the ink pixels
- Subtract - removes the canvas pixels from the ink pixels
- Average - blends the canvas and ink pixels, taking the average value
- Fade - brighten or darken the canvas pixels
- Min - where the ink is not 0, choose the darker pixel between the ink and the canvas. If the ink is 0, leave the canvas unchanged.
- Max - where the ink is not 0, choose the brighter pixel between the ink and the canvas. If the ink is 0, leave the canvas unchanged.
The brush describes the pattern the pen will draw with:
- Pencil - drawing by single pixels of a solid colour ink
- Smear - (Not complete)
- Stamp - draw with a pattern aligned to the shape
- Stretch - (Not complete) Resize the pattern to fit a shape
- Tile - draw with a pattern aligned to the canvas
Not all pen modes are available on all kinds of canvas.
=> pen.set_pen_mode( canvas_id, pen_mode.copy )
=> pen.set_pen_brush( canvas_id, pen_brush.pencil)
=> pen.set_pen_ink( canvas_id, 100, 0, 0 )
These commands set the pen brush to a pencil (single pixels) and the mode to copy (the
pencil pixels will overwrite whatever pixels currently on the canvas background). The
pen pixels will be bright red.
pen.fill_ellipse( c, r )
Fill ellipse bounded by rectangle r in canvas c using the current pen.
Example: pen.fill_ellipse( canvas_id, pie_graph_rect );
Ada Equivalent: N/A - Pen.fillRect (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rect |
required |
the rectangle surrounding ellipse to fill |
|
pen.fill_rect( c, r )
Fill rectange r in canvas c using the current pen.
Example: pen.fill_rect( canvas_id, background_rect );
Ada Equivalent: N/A - Pen.fillRect (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rect |
required |
the rectangle to fill |
|
pen.frame_ellipse( c, r )
Draw an outline around ellipse bounded by rectangle r in canvas c using the current pen.
Example: pen.fill_ellipse( canvas_id, pie_graph_rect );
Ada Equivalent: N/A - Pen.frameRect (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rect |
required |
the rectangle surrounding ellipse to border |
|
pen.frame_rect( c, r )
Draw an outline around rectange r in canvas c using the current pen.
Example: pen.frame_rect( canvas_id, background_rect );
Ada Equivalent: N/A - Pen.fillRect (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rect |
required |
the rectangle to border |
|
b := pen.get_pen_brush( c )
Return the current pen brush for canvas c.
Example: pen_brush := pen.get_pen_brush( canvas_id );
Ada Equivalent: N/A - Pen.getPenBrush (BUSH package)
Parameters:
b |
result |
pen.pen_brush |
required |
the pattern application mode |
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
|
pen.get_pen_ink( c, r, g, b )
Return the current pen solid drawing colour in canvas c.
Example: pen.get_pen_ink( canvas_id, red, green, blue );
Ada Equivalent: N/A - Pen.getPenInk (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rgbcomponent |
required |
percentage of red in the color |
g |
in |
pen.rgbcomponent |
required |
percentage of green in the color |
b |
in |
pen.rgbcomponent |
required |
percentage of blue in the color |
|
m := pen.get_pen_mode( c )
Return the current pen mode for canvas c.
Example: pen_mode := pen.get_pen_mode( canvas_id );
Ada Equivalent: N/A - Pen.getPenMode (BUSH package)
Parameters:
m |
result |
pen.pen_mode |
required |
the pen mode |
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
|
pen.hline( c, x1, x2, y )
Draw a horizontal line between (x1,y) and (x2,y) on canvas c in the current pen.
Example: pen.hline( canvas_id, 0, 100, 50);
Ada Equivalent: N/A - Pen.hline (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
x1 |
in |
pen.coordinate |
required |
the left-most x coordinate |
x2 |
in |
pen.coordinate |
required |
the right-most x coordiante |
y |
in |
pen.coordinate |
required |
the y coordinate |
|
b := pen.in_rect( x, y, r )
True if point (x, y) is inside of rectangle r.
Example: b := pen.in_rect( mouse_x, mouse_y, icon_rect );
Ada Equivalent: N/A - Pen.in_rect (BUSH package)
Parameters:
b |
result |
boolean |
required |
true if ir is contained in or |
x |
in |
pen.coordinate |
required |
the horizontal position |
yr |
in |
pen.coordinate |
required |
the vertical position |
|
pen.inset_rect( r, dx, dy )
Change the size of the rectangle by dx horizontal and dy vertical. Negative values cause
the rectangle to grow. The center of the rectangle remains unchanged.
Example: pen.inset_rect( shrinking_rect, 10, 10 ); -- shrink by 10% of canvas
Ada Equivalent: N/A - Pen.inset_rect (BUSH package)
Parameters:
r |
in out |
pen.rect |
required |
the rectangle to shift |
dx |
in |
pen.coordinate |
required |
the horizontal change to the left and right |
dy |
in |
pen.coordinate |
required |
the vertical change to the top and bottom |
|
b := pen.inside_rect( ir, or )
True if ir is a rectangle inside of rectangle or.
Example: b := pen.inside_rect( small_rect, big_rect );
Ada Equivalent: N/A - Pen.inside_rect (BUSH package)
Parameters:
b |
result |
boolean |
required |
true if ir is contained in or |
ir |
in |
pen.rect |
required |
the inner rectangle |
or |
in |
pen.rect |
required |
the outer rectangle |
|
pen.intersect_rect( r, r1, r2 )
Calculate the overlap rectangle (if any) between rectangles r1 and r2.
Example: pen.intersect_rect( overlap_rect, player_sprite, monster_sprite );
Ada Equivalent: N/A - Pen.intersect_rect (BUSH package)
Parameters:
r |
out |
pen.rect |
required |
the intersection rect or empty rect if none |
r1 |
in |
pen.rect |
required |
a rectangle |
r2 |
in |
pen.rect |
required |
a rectangle |
|
b := pen.is_empty_rect( r )
True if r is a rectangle that contains nothing.
Example: bool := pen.is_empty_rect( some_rect );
Ada Equivalent: N/A - Pen.isEmptyRect (BUSH package)
Parameters:
c |
result |
boolean |
required |
true if rectangle is empty |
r |
in |
pen.rect |
required |
the rectangle to test |
|
pen.line( c, dx, dy )
Draw a line in the current pen from the current pen position to a new relative position
offset by dx and dy.
Example: pen.line( canvas_id, 0, 10 );
Ada Equivalent: N/A - Pen.line (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
dx |
in |
pen.coordiante |
required |
the horizontal change from the current pen position |
dy |
in |
pen.coordiante |
required |
the vertical change from the current pen position |
|
pen.line_to( c, x, y )
Draw a line with the pen from the current pen position to a new position (x,y).
Example: pen.line_to( canvas_id, 75, 10 );
Ada Equivalent: N/A - Pen.line (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
x |
in |
pen.coordiante |
required |
the new horizontal position |
y |
in |
pen.coordiante |
required |
the new vertical position |
|
pen.move( c, dx, dy )
Move the pen from the current pen position to a new relative position
offset by dx and dy. No line will be drawn.
Example: pen.move( canvas_id, 0, 10 );
Ada Equivalent: N/A - Pen.move (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
dx |
in |
pen.coordiante |
required |
the horizontal change from the current pen position |
dy |
in |
pen.coordiante |
required |
the vertical change from the current pen position |
|
pen.move_to( c, x, y )
Move the pen from the current pen position to a new position (x,y). No line will be
drawn.
Example: pen.move_to( canvas_id, 75, 10 );
Ada Equivalent: N/A - Pen.move (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
x |
in |
pen.coordiante |
required |
the new horizontal position |
y |
in |
pen.coordiante |
required |
the new vertical position |
|
pen.new_canvas( h, v, c, id ) pen.new_canvas( s, id )
Create a new drawing area canvas that does not appear on the display. If the first
parameter is a string, load the image file from path s into a canvas big enough to hold it.
Example: pen.new_canvas( 100, 100, 16, canvas_id );
Example: pen.new_canvas( "company_logo.png", logo_id );
Ada Equivalent: N/A - Pen.newCanvas (BUSH package)
Parameters:
h |
in |
positive |
required |
the minimum horizontal size in pixels |
v |
in |
positive |
required |
the minimum vertical size in pixels |
c |
in |
positive |
required |
the minimum pixel bits (8, 16, 24 or 32) |
id |
out |
pen.canvas_id |
required |
the identification number for the offscreen canvas |
s |
in |
universal_string |
required |
the path to a file that SDL_image can load (JPEG, GIF, PNG, etc.) |
|
pen.new_screen_canvas( h, v, c, id )
Create a new drawing area canvas that covers the entire display screen.
Example: pen.new_screen_canvas( 100, 100, 16, canvas_id );
Ada Equivalent: N/A - Pen.newScreenCanvas (BUSH package)
Parameters:
h |
in |
positive |
required |
the minimum horizontal size in pixels |
v |
in |
positive |
required |
the minimum vertical size in pixels |
c |
in |
positive |
required |
the minimum pixel bits (8, 16, 24 or 32) |
id |
out |
pen.canvas_id |
required |
the identification number for the new canvas |
|
pen.new_window_canvas( h, v, c, id )
Create a new drawing area canvas in a separate operating system window.
Example: pen.new_window_canvas( 100, 100, 16, canvas_id );
Ada Equivalent: N/A - Pen.newWindowCanvas (BUSH package)
Parameters:
h |
in |
positive |
required |
the minimum horizontal size in pixels |
v |
in |
positive |
required |
the minimum vertical size in pixels |
c |
in |
positive |
required |
the minimum pixel bits (8, 16, 24 or 32) |
id |
out |
pen.canvas_id |
required |
the identification number for the new canvas |
|
pen.offset_rect( r, dx, dy )
Move rectangle by dx horizontal and dy vertical. The size of the rectangle remains
unchanged.
Example: pen.offset_rect( player_sprite, 1, 0 );
Ada Equivalent: N/A - Pen.offset_rect (BUSH package)
Parameters:
r |
in out |
pen.rect |
required |
the rectangle to shift |
dx |
in |
pen.coordinate |
required |
the horizontal change to the left and right |
dy |
in |
pen.coordinate |
required |
the vertical change to the top and bottom |
|
pen.set_pen_brush( c, b )
Change the current pen brush (pattern application mode) for canvas c.
Example: pen.set_pen_brush( canvas_id );
Ada Equivalent: N/A - Pen.setPenBrush (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
b |
result |
pen.brush |
required |
the new pattern application mode |
|
pen.set_pen_ink( c, r, g, b )
Change the current pen solid drawing colour in canvas c.
Example: pen.set_pen_ink( canvas_id, red, green, blue );
Ada Equivalent: N/A - Pen.setPenInk (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
r |
in |
pen.rgbcomponent |
required |
percentage of red in the color |
g |
in |
pen.rgbcomponent |
required |
percentage of green in the color |
b |
in |
pen.rgbcomponent |
required |
percentage of blue in the color |
|
m := pen.set_pen_mode( c )
Change the current pen mode for canvas c.
Example: pen_mode := pen.get_pen_mode( canvas_id );
Ada Equivalent: N/A - Pen.getPenMode (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
m |
in |
pen.pen_mode |
required |
the pen mode |
|
pen.set_pen_pattern( c, pid )
Change the drawing pattern of canvas c to canvas pid.
Example: pen.set_pen_pattern( canvas_id, company_logo_canvas_id );
Ada Equivalent: N/A - Pen.setPenPattern (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
pid |
in |
pen.canvas_id |
required |
the canvas to use as the drawing pattern |
|
pen.set_rect( r, l, t, r, b )
Assign coordinates to a rectangle.
Example: set_rect( full_canvas, 0, 0, 100, 100 );
Ada Equivalent: N/A - Pen.setRect (BUSH package)
Parameters:
r |
in |
pen.rect |
required |
the rectangle |
l |
in |
pen.coordinate |
required |
the left coordinate |
t |
in |
pen.coordinate |
required |
the top coordinate |
r |
in |
pen.coordinate |
required |
the right coordinate |
b |
in |
pen.coordinate |
required |
the bottom coordinate |
|
pen.set_title( c, t )
Change the title of canvas c to string t. On a window canvas, update the
window title bar.
Example: set_title( canvas_id, "Graph of Results" );
Ada Equivalent: N/A - Pen.setTitle (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
t |
in |
universal_string |
required |
the new title |
|
pen.vline( c, x, y1, y2 )
Draw a vertical line between (x,y1) and (x,y2) on canvas c in the current pen.
Example: pen.set_vline( canvas_id, 50, 0, 100);
Ada Equivalent: N/A - Pen.hline (BUSH package)
Parameters:
c |
in |
pen.canvas_id |
required |
the drawing area canvas |
x |
in |
pen.coordinate |
required |
the x coordinate |
y1 |
in |
pen.coordinate |
required |
the top-most y coordiante |
y2 |
in |
pen.coordinate |
required |
the bottom-most y coordinate |
|
Back to Top
|