NOTE: This package is under construction. The features have not been finalized.
The pen package is the SparForte 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.
Colors are made of percentages of red, green and blue. pen.pen_color_name
is an enumerated type with the standard X windows color names.
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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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. Ignores clipping region.
Example: pen.hline( canvas_id, 0, 100, 50);
Ada Equivalent: N/A - Pen.hline (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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_gl_screen_canvas( h, v, c, id )
Create a new OpenGL drawing area canvas that covers the entire display
screen.
Example: pen.new_screen_canvas( 100, 100, 16, canvas_id );
Ada Equivalent: N/A - Pen.newGLScreenCanvas (SparForte 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_gl_window_canvas( h, v, c, id )
Create a new OpenGL drawing area canvas in a separate
operating system window.
Example: pen.new_gl_window_canvas( 100, 100, 16, canvas_id );
Ada Equivalent: N/A - Pen.newGLWindowCanvas (SparForte 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_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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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 ) pen.set_pen_ink( c, n )
Change the current pen solid drawing colour in canvas c.
Example: pen.set_pen_ink( canvas_id, red, green, blue );
pen.set_pen_ink( canvas_id, pen.color_name.skyblue );
Ada Equivalent: N/A - Pen.setPenInk (SparForte 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
n
in
pen.pen_color_name
required
the name of the colour
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 (SparForte 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 (SparForte 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 (SparForte 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 (SparForte 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. Ignores clipping region.
Example: pen.set_vline( canvas_id, 50, 0, 100);
Ada Equivalent: N/A - Pen.vline (SparForte package)
Parameters:
![[SparForte]](art/sparforte.png)
![[Banner]](art/header_cloud.png)
![[Top Main Menu]](art/menu_left.png)
![[Back Page]](art/left_arrow.png){kind=icon}
![[Next Page]](art/right_arrow.png){kind=icon}
![[A Window Canvas]](pictures/pen_window.gif)
![[Right Submenu]](art/right_menu_top.png){kind=small}
![[Back to Top]](art/up_arrow.png){kind=icon}
Back To Top![[Small Forte Symbol]](art/forte_small.png){kind=small}