[BUSH User Guide]
 
Home Page Introduction Tutorials Reference Packages Hacking
 
  Packages  
4.1 Using Packages
4.2 text_io (Console I/O)
4.3 text_io (File I/O)
4.4 sound
4.5 source_info
4.6 System
4.7 numerics
4.8 strings
4.9 command_line
4.10 lock_files
4.11 cgi
4.12 calendar
4.13 units
4.14 arrays
4.15 files
4.16 db (Database)
4.17 stats
4.18 pen
4.19 mysql
4.20 os
 
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.

[A Window 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