![]() | ![]() | |||||||||||||||
|
Pen PackageNOTE: 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:
Pen modes include:
The brush describes the pattern the pen will draw with:
Not all pen modes are available on all kinds of canvas.
Colors are made of percentages of red, green and blue. pen.color_name is an enumerated type with the standard X windows color names. => 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. This is how you would load and draw an image. (Not all features are supported yet.) => pen.set_rect( r, 0, 0, 100, 100 ) => (Assuming r is a new pen.rect variable) => pen.new_window_canvas( 100,100, 32, c ) => (Assuming c is a new pen.canvas_id variable) => pen.new_canvas("i.png", img ) => (Assuming img is a new pen.canvas_id variable) => pen.set_pen_pattern( c, img ) => pen.set_pen_brush( c, pen_brush.tile ) => pen.set_pen_mode( c, pen_mode.copy ) => pen.paint_rect(c, r ) set_rect(r, l, t, r, b) b := is_empty_rect( r ) offset_rect( r, dx, dy ) inset_rect( r, dx, dy ) intersect_rect( r,r1,r2) b := inside_rect( ir, or ) b := in_rect( x, y, r ) frame_ellipse( id, r ) frame_rect( id, r ) fill_ellipse( id, r ) paint_rect( id, r ) fill_rect(id,rct,r,g,b) fill_rect(id,r,cn) line_to( id, x, y ) line( id, dx, dy ) hline( id, x1, x2, y ) vline( id, x, y1, y2 ) move_to( id, x, y ) move( id, dx, dy ) clear clear( r, g, b) clear( cn ) get_pen_mode( id ) get_pen_brush( id ) set_pen_ink(id,r,g,b) set_pen_ink(id,cn) set_pen_mode( id, m) set_pen_pattern( id,pid) set_pen_brush( id,brush ) set_font( c, f, p )* put( c, s )* p := greyscale( r,g,b) blend(r1,g1,b1,r2,g2,b2,r,g,b) fade(r1,g1,b1,p,r,g,b) new_canvas(h,v,c,id) new_screen_canvas(h,v,c,id) new_window_canvas(h,v,c,id) new_canvas(p,id) new_gl_screen_canvas(h,v,c,id) save_canvas(p,id) close_canvas( id ) wait_to_reveal( id ) reveal( id ) reveal_now( id )
Help Command: Contents of the pen package
pen.blend( r1, g1, b1, r2 ,g2 ,b2 ,r, g, b )
pen.clear( c )
|
Fill the drawing area with the specified color. The color may be specified as a color name or an RGB percentage value. If the color name is omitted, the current pen color is used. It is the equivalent of paint_rect/fill_rect on the entire canvas, or the built-in clear command for a terminal session. |
||||||||||||||||||||||||||||||||||||
Example |
pen.clear( my_canvas, pen_color_name.turquoise ); | |||||||||||||||||||||||||||||||||||
Parameters |
|
|||||||||||||||||||||||||||||||||||
Exceptions |
- | |||||||||||||||||||||||||||||||||||
See Also |
pen.paint_rect | |||||||||||||||||||||||||||||||||||
Compare With |
- |
Brighten or darken a color by percentage p and return the resulting RGB colour. The color will be brightened if the percentage is negative. The resulting color will never have components more than 100.0 or less than 0.0. |
|||||||||||||||||||||||||||||||||||||||||
Example |
pen.fade( 100, 100, 50, 50, r, g, b); -- RGB will be 50/50/25 | ||||||||||||||||||||||||||||||||||||||||
Parameters |
|
||||||||||||||||||||||||||||||||||||||||
Exceptions |
- | ||||||||||||||||||||||||||||||||||||||||
See Also |
pen.blend | ||||||||||||||||||||||||||||||||||||||||
Compare With |
- |
Fill ellipse bounded by rectangle r in canvas c using the specified RGB color or color name. If wait_to_reveal is used, the results will not appear until revealed. |
|||||||||||||||||||||||||||||||||||||||||
Example |
=> pen.new_window_canvas( 100, 100, 32, c ) | ||||||||||||||||||||||||||||||||||||||||
Parameters |
|
||||||||||||||||||||||||||||||||||||||||
Exceptions |
- | ||||||||||||||||||||||||||||||||||||||||
See Also |
pen.frame_rect | ||||||||||||||||||||||||||||||||||||||||
Compare With |
- |
||||||||||||||||||||||||||||||||||||||||
Known Bugs |
An ellipse in a (0,0,100,100) rectangle throws an exception due to a rounding error. |
Fill rectangle rt in canvas c using the specified RGB color or color name. If wait_to_reveal is used, the results will not appear until revealed. |
|||||||||||||||||||||||||||||||||||||||||
Example |
=> pen.new_window_canvas( 100, 100, 32, c ) | ||||||||||||||||||||||||||||||||||||||||
Parameters |
|
||||||||||||||||||||||||||||||||||||||||
Exceptions |
- | ||||||||||||||||||||||||||||||||||||||||
See Also |
pen.frame_rect | ||||||||||||||||||||||||||||||||||||||||
Compare With |
- |
Draw an outline around ellipse bounded by rectangle r in canvas c using the current pen. If wait_to_reveal is used, the results will not appear until revealed. |
||||||||||||||||
Example |
pen.frame_ellipse( canvas_id, pie_graph_rect ); | |||||||||||||||
Parameters |
|
|||||||||||||||
Exceptions |
- | |||||||||||||||
See Also |
pen.fill_ellipse | |||||||||||||||
Compare With |
- |
|||||||||||||||
Bugs |
An ellipse in a (0,0,100,100) rectangle throws an exception due to a rounding error. |
Draw an outline around rectangle r in canvas c using the current pen. If wait_to_reveal is used, the results will not appear until revealed. |
||||||||||||||||
Example |
pen.frame_rect( canvas_id, background_rect ); | |||||||||||||||
Parameters |
|
|||||||||||||||
Exceptions |
- | |||||||||||||||
See Also |
pen.clear | |||||||||||||||
Compare With |
- |
Return the current pen brush for canvas c. |
||||||||||||||||
Example |
pen_brush := pen.get_pen_brush( canvas_id ); | |||||||||||||||
Parameters |
|
|||||||||||||||
Exceptions |
- | |||||||||||||||
See Also |
pen.set_pen_brush | |||||||||||||||
Compare With |
- |
Return the current pen solid drawing colour in canvas c. |
||||||||||||||||||||||||||
Example |
pen.get_pen_ink( canvas_id, red, green, blue ); | |||||||||||||||||||||||||
Parameters |
|
|||||||||||||||||||||||||
Exceptions |
- | |||||||||||||||||||||||||
See Also |
pen.set_pen_ink | |||||||||||||||||||||||||
Compare With |
- |
Return the current pen mode for canvas c. |
||||||||||||||||
Example |
pen_mode := pen.get_pen_mode( canvas_id ); | |||||||||||||||
Parameters |
|
|||||||||||||||
Exceptions |
- | |||||||||||||||
See Also |
pen.set_pen_mode | |||||||||||||||
Compare With |
- |
Compute the greyscale for the RGB color and return the RGB percentage (where RGB will be the same). This is weighted for the human eye. |
||||||||||||||||||||||||||
Example |
p := pen.greyscale( 10, 20, 30 ); | |||||||||||||||||||||||||
Parameters |
|
|||||||||||||||||||||||||
Exceptions |
- | |||||||||||||||||||||||||
See Also |
pen.blend | |||||||||||||||||||||||||
Compare With |
- |
Draw a horizontal line between (x1,y) and (x2,y) on canvas c in the current pen. Ignores clipping region. If wait_to_reveal is used, the results will not appear until revealed. |
||||||||||||||||||||||||||
Example |
pen.hline( canvas_id, 0, 100, 50); | |||||||||||||||||||||||||
Parameters |
|
|||||||||||||||||||||||||
Exceptions |
- | |||||||||||||||||||||||||
See Also |
pen.line | |||||||||||||||||||||||||
Compare With |
- |
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:
|
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:
|
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:
|
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:
|
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:
|
Draw a line in the current pen from the current pen position to a new relative position offset by dx and dy. If wait_to_reveal is used, the results will not appear until revealed. Example: pen.line( canvas_id, 0, 10 ); Ada Equivalent: N/A - Pen.line (SparForte package) Parameters:
|
Draw a line with the pen from the current pen position to a new position (x,y). If wait_to_reveal is used, the results will not appear until revealed. Example: pen.line_to( canvas_id, 75, 10 ); Ada Equivalent: N/A - Pen.line (SparForte package) Parameters:
|
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:
|
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:
|
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. Otherwise, the parameters are the horizontal and vertical dimensions of the new canvas and the canvas id of an existing on-screen canvas to copy over any additional settings. To apply the contents of the canvas to the on-screen canvas, use set_pen_pattern. Example: pen.new_canvas( 100, 100, main_canvas_id, hidden_canvas_id ); Example: pen.new_canvas( "company_logo.png", logo_id ); Ada Equivalent: N/A - Pen.newCanvas (SparForte package) Parameters:
|
An exception may be thrown if the existing canvas does not exist.
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:
|
Create a new OpenGL drawing area canvas in a separate operating system window. Multiple windows may not be supported by the SDL library. Example: pen.new_gl_window_canvas( 100, 100, 16, canvas_id ); Ada Equivalent: N/A - Pen.newGLWindowCanvas (SparForte package) Parameters:
|
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:
|
Create a new drawing area canvas in a separate operating system window. Multiple windows may not be supported by the SDL library. Example: pen.new_window_canvas( 100, 100, 16, canvas_id ); Ada Equivalent: N/A - Pen.newWindowCanvas (SparForte package) Parameters:
|
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:
|
Fill ellipse bounded by rectangle r in canvas c using the current pen. If wait_to_reveal is used, the results will not appear until revealed. |
||||||||||||||||
Example |
pen.paint_ellipse( canvas_id, pie_graph_rect ); | |||||||||||||||
Parameters |
|
|||||||||||||||
Exceptions |
- | |||||||||||||||
See Also |
pen.frame_ellipse | |||||||||||||||
Compare With |
- |
|||||||||||||||
Known Bugs |
An ellipse in a (0,0,100,100) rectangle throws an exception due to a rounding error. |
Fill rectangle r in canvas c using the current pen. If wait_to_reveal is used, the results will not appear until revealed. Example: pen.frame_rect( canvas_id, background_rect ); Ada Equivalent: N/A - Pen.fillRect (SparForte package) Parameters:
|
Undo a wait_to_reveal. The time of hiding the drawing has been completed and the results are ready to be shown. Repeated use of this function decrements a counter and the results are not shown until all reveals are performed (to allow the drawing to be nested). Example: pen.reveal( c ) Ada Equivalent: N/A - Pen (SparForte package) Parameters:
|
Undo all wait_to_reveal calls and immediately show the results of any hidden drawing. Further drawing will be immediately visible. This is intended for debugging or use at the command prompt. Further reveal's will have no effect. Example: pen.reveal_now( c ) Ada Equivalent: N/A - Pen (SparForte package) Parameters:
|
pen.save_canvas( s, id )
Save the canvas as a BMP image file. An exception is raised if the image cannot be saved. Example: pen.save_canvas( "company_logo.png", logo_id ); Ada Equivalent: N/A - Pen Parameters:
|
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:
|
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:
|
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:
|
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:
|
Assign coordinates to a rectangle. Example: set_rect( full_canvas, 0, 0, 100, 100 ); Ada Equivalent: N/A - Pen.setRect (SparForte package) Parameters:
|
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:
|
Begin to hide the results of the drawing commands. Continue to hide until revealed when the final results are shown. Repeated use of this function increments a counter and the results are not shown until all reveals are performed (to allow the drawing to be nested). This call speeds drawing in two ways (1) it only shows the final result in the case of overlapping drawing, (2) the display will not have to be refreshed after each drawing operation. Example: pen.wait_to_reveal( c ) Ada Equivalent: N/A - Pen (SparForte package) Parameters:
|
Draw a vertical line between (x,y1) and (x,y2) on canvas c in the current pen. Ignores clipping region. If wait_to_reveal is used, the results will not appear until revealed. Example: pen.set_vline( canvas_id, 50, 0, 100); Ada Equivalent: N/A - Pen.vline (SparForte package) Parameters:
|