s9fes-char-graphics (historical revision 44592)

You are looking at historical revision 44592 of this page. It may differ significantly from its current revision.

s9fes-char-graphics

A Shape extemsopm tp the Scheme 9 from Empty Space'' character graphics library; the s9fes-char-graphics-shape egg.

s9fes-char-graphics
Bugs & Limitations
Notes
Requirements
Author
Repository
Version history
License

Char Canvas Shape Shared Arguments & Types:

Shapes are functions, either taking no arguments and returning the constructing parameters, or taking at least a canvas, rendering the shape, then returning the canvas.

real-shape-plotter: ([CANVAS [X0 [Y0]]] -> (or CANVAS PARAMS))
X0 Y0: fixnum fixnum ; center
PARAMS: (list symbol symbol ...) ; defining parameters (from the constructor)
shape-plotter: ([CANVAS [X0 [Y0]]] -> (or CANVAS PARAMS))
X0 Y0: integer integer ; center
PARAMS: (list symbol symbol ...) ; defining parameters (from the constructor)

real-shape-plotter is-a shape-plotter, just restricted to real coordinates.

The PARAMS are prefixed with a shape kind & coordinate-system.

Char Canvas Shape Shape

Usage

(import (s9fes char-canvas shape shape))

Shared Arguments & Types

SHAPE: shape-plotter ; argument type, includes real-shape-plotter

All error when the {SHAPE}} is unknown.

shape-coords

[procedure] (shape-class SHAPE) -> symbol
[procedure] (shape-coords SHAPE) -> symbol

shape-size

[procedure] (shape-size SHAPE) -> integer integer

Returns the width & height (columns & rows) for the SHAPE.

shape-center

[procedure] (shape-size SHAPE) -> integer integer integer integer

Returns the floor ceiling of the SHAPE center.

shape-cardinality

[procedure] (shape-cardinality SHAPE) -> fixnum

Count of grouped shapes.

shape-elements

[procedure] (shape-elements SHAPE) -> (list-of shape)

Grouped shapes.

shape-layout

[procedure] (shape-layout SHAPE BB) -> shape

Returns a static SHAPE (no elastic elemetns) for the supplied SHAPE.

BB: rect ; bounding-box, available space for layout

shape-justified?

[procedure] (shape-justified? SHAPE) -> boolean

Returns whether the SHAPE is static;no elastic elemetns.

shape-show

[procedure] (shape-show SHAPE CANVAS X Y) -> canvas

By default (SHAPE CANVAS X Y), but up to the SHAPE.

shape-fold

[procedure] (shape-fold SHAPE FUNC SEED) -> SEED-TYPE

SEED-TYPE: 'a ; type-of SEED
FUNC: (shape-plotter 'a -> 'a) ;

registered-shapes

[procedure] (registered-shapes) -> (list-of symbol)

registered-shape-methods

[procedure] (registered-shape-methods ID) -> (list-of symbol)

ID: symbol : shape name

Char Canvas Shape Box

Usage

(import (s9fes char-canvas shape box))

Shared Arguments & Types

FRAME: (vector char char char char char char char char) ; top/bottom horizontal, top/bottom vertical, corner top left/right & bottom left/right chars; default #(#\- #\- #\| #\| #\+ #\+ #\+ #\+).
FRAME: #t ; use ASCII-FRAME-CHARS.

real-shape-box

[procedure] (real-shape-box WD HT [FRAME]) -> real-shape-plotter

WD: fixnum ; width
HT: fixnum ; height

shape-box

[procedure] (shape-box WD HT [FRAME]) -> shape-plotter

WD: integer ; width
HT: integer ; height

Char Canvas Shape Circle

Usage

(import (s9fes char-canvas shape circle))

Shared Arguments & Types:

octant-plotter: (canvas fixnum fixnum fixnum fixnum -> boolean) ; returns continue?
octant-visitor: (canvas fixnum fixnum -> boolean) ; returns continue?

real-shape-circle

[procedure] (real-shape-circle R [CONFIG]) -> real-shape-plotter

R: fixnum ; radius

shape-circle

[procedure] (shape-circle R [CONFIG]) -> shape-plotter

R: integer ; radius
CONFIG: (or false char plotter-configuration) ; octant drawing pattern, 8 elements, octant 0 to octant 8, #f for skip or a char to draw; default is (current-plotter-char).

(import (s9fes char-canvas) (s9fes char-canvas shape circle))

(define canvas-plot-circle@40 (shape-circle 40))

(let ((cv (make-canvas 10 10 100 100)))
  (canvas-plot-circle@40 cv 50 50)
  (canvas-print cv #t) )
;=>
+----------+
|    ***   |
|   *   *  |
|  *     * |
| *       *|
| *       *|
| *       *|
|  *     * |
|   *   *  |
|    ***   |
|          |
+----------+

circle-polygon-lines

[procedure] (circle-polygon-lines X0 Y0 RADIUS [N [ANGLE]) -> (list-of integer)

Returns a list of virtual coordinates suitable for use w/ canvas-plot-lines. A closed, convex, polygon is described.

X0 Y0: integer integer ; circle center in virtual coordinates
RADIUS: integer ; circle radius in virtual coordinates
N: fixnum ; number of points ; default 360
ANGLE: fixnum ; starting degree ; default 0

(import (s9fes char-canvas) (s9fes char-canvas shape circle))

(let ((cv (make-canvas 10 10 100 100)))
  (canvas-plot-lines cv (circle-polygon-lines 50 50 50))
  (canvas-print cv) )
;=>
  ******
 *      *
*        *
*        *
*        *
*        *
*        *
*        *
 *      *
  ******

Note how restricting the number of segments coarsens the image, even clipping. ((circle-polygon-lines 50 50 49 4) produces an ok diamond.)

(let ((cv (make-canvas 10 10 100 100)))
  (canvas-plot-lines cv (circle-polygon-lines 50 50 50 4))
  (canvas-print cv #t) )
;=>
+----------+
|    * *   |
|   *   *  |
|  *     * |
| *       *|
|*         |
| *       *|
|  *    ** |
|  *   *   |
|   * *    |
|    *     |
+----------+

circle-octant-plotter

[procedure] (circle-octant-plotter [CONFIG]) -> octant-plotter

Returns a canvas-drawing procedure for the specified octant drawing pattern CONFIG.

CONFIG: (or false char plotter-configuration) ; octant drawing pattern, 8 elements, octant 0 to octant 8, #f for skip or a char to draw; default is (current-plotter-char).

generate-circle-octant

[procedure] (generate-circle-octant CANVAS RADIUS VISITOR)

Generates the coordinates for the first octant of a circle of RADIUS. It uses real coordinates. The VISITOR is called for each generated point. Should the VISITOR return #f the generator halts early.

RADIUS: fixnum ; radius
VISITOR: octant-visitor

circle-octant-point

[procedure] (circle-octant-point OCTANT X0 Y0 X Y) -> fixnum fixnum

Returns coordinates for octant 0 point X Y in the specified OCTANT, center at X0 Y0.

OCTANT: fixnum ; octant, 0..7, coordinates to calculate
X0 Y0: fixnum fixnum ; center
X Y: fixnum fixnum ; offset

circle-octant-visitor

[procedure] (circle-octant-visitor X0 Y0 PLOTTER) -> octant-visitor

X0 Y0: fixnum fixnum ; center
PLOTTER: octant-plotter

generate-virtual-circle-octant

[procedure] (generate-virtual-circle-octant CANVAS RADIUS VISITOR [AVERAGE?])

Same as generate-circle-octant but w/ virtual coordinates (see above).

RADIUS: integer ; radius
VISITOR: octant-visitor

(import (s9fes char-canvas) (s9fes char-canvas shape circle))

(define (canvas-draw-circle cv c r w #!optional (pl (circle-octant-plotter)))
  (generate-circle-octant cv w (circle-octant-visitor c r pl)) )

(let* ((rw 5) (cl 5)
       (cr (quotient rw 2)) (cc (quotient cl 2)) (rd cc)
       (cv (make-canvas cl rw)) )
  (canvas-draw-circle cv cc cr rd)
  (canvas-print cv) )
;=>
 ***
*   *
*   *
*   *
 ***

virtual-circle-octant-visitor

[procedure] (virtual-circle-octant-visitor X0 Y0 PLOTTER) -> octant-visitor

Same as circle-octant-visitor but w/ virtual coordinates (see above).

X0 Y0: integer integer ; center
PLOTTER: octant-plotter

(import (s9fes char-canvas) (s9fes char-canvas shape circle))

(define (canvas-plot-circle cv x y r #!optional (pl (circle-octant-plotter)))
  (generate-virtual-circle-octant cv r (virtual-circle-octant-visitor x y pl)) )

(let* ((rw 5) (cl 5) (wd 100) (ht 250)
       (x0 (round (/ wd 2))) (y0 (round (/ ht 2))) (rd y0)
       (cv (make-canvas rw cl wd ht)) )
  (canvas-plot-circle cv x0 y0 rd)
  (canvas-print cv) )
;=>
 ***
*   *
*   *
*   *
 ***

Char Canvas Shape Cross

Usage

(import (s9fes char-canvas shape cross))

Char Canvas Shape Cross Shared Arguments & Types:

CONFIG: (or false char plotter-configuration) ; drawing pattern, 2 elements, #f for skip or a char to draw; default is (current-plotter-char).

real-shape-cross--

real-shape-cross-vbar

real-shape-cross-+

[procedure] (real-shape-cross-- WD [HT [CONFIG]]) -> real-shape-plotter
[procedure] (real-shape-cross-vbar WD [HT [CONFIG]]) -> real-shape-plotter
[procedure] (real-shape-cross-+ WD [HT [CONFIG]]) -> real-shape-plotter

WD: fixnum
HT: fixnum ; default WD

real-shape-cross-obar

real-shape-cross-abar

real-shape-cross-x

[procedure] (real-shape-cross-obar WD [HT [CONFIG]]) -> real-shape-plotter
[procedure] (real-shape-cross-abar WD [HT [CONFIG]]) -> real-shape-plotter
[procedure] (real-shape-cross-x WD [HT [CONFIG]]) -> real-shape-plotter

WD: fixnum
HT: fixnum ; default WD

shape-cross--

shape-cross-vbar

shape-cross-+

[procedure] (shape-cross-- WD [HT [CONFIG]]) -> shape-plotter
[procedure] (shape-cross-vbar WD [HT [CONFIG]]) -> shape-plotter
[procedure] (shape-cross-+ WD [HT [CONFIG]]) -> shape-plotter

WD: integer
HT: integer ; default WD

shape-cross-obar

shape-cross-abar

shape-cross-x

[procedure] (shape-cross-obar WD [HT [CONFIG]]) -> shape-plotter
[procedure] (shape-cross-abar WD [HT [CONFIG]]) -> shape-plotter
[procedure] (shape-cross-x WD [HT [CONFIG]]) -> shape-plotter

WD: integer
HT: integer ; default WD

(import (s9fes char-canvas) (s9fes char-canvas shape cross))

(define canvas-plot-x@100x100 (shape-cross-x 100))

(let ((cv (make-canvas 10 5 100 100)))
  (canvas-plot-x@100x100 cv)
  (canvas-print cv) )
;=>
**      **
  **  **
    **
  **  **
**      **

Char Canvas Shape image

Usage

(import (s9fes char-canvas shape image))

read-image

write-image

load-image

store-image

canvas->image

string->image

real-shape-image

shape-image

[procedure] (read-image [IN]) -> image
[procedure] (write-image IMAGE [OUT])
[procedure] (load-image PATH) -> image
[procedure] (store-image IMAGE PATH)
[procedure] (canvas->image CANVAS) -> image
[procedure] (string->image STR) -> image

images are "composited" using the (current-plotter-bkgd-char) as the "alpha-channel". Source background is ignored and only foreground characters are placed. (see canvas-paste)

[procedure] (real-shape-image IMAGE [TRANS]]) -> real-shape-plotter
[procedure] (shape-image IMAGE [TRANS]]) -> shape-plotter

Char Canvas Shape Fpad

Usage

(import (s9fes char-canvas shape fpad))

real-shape-fpad

shape-fpad

[procedure] (real-shape-fpad SHAPE DIMS [CHARS]) -> real-shape-plotter
[procedure] (shape-fpad SHAPE DIMS [CHARS])) -> shape-plotter

DIMS: {[integer integer integer integer]} ; top bottom left right
CHARS: {[(or false char) (or false char) (or false char) (or false char)]} ; top bottom left right

Char Canvas Shape jpad

Usage

(import (s9fes char-canvas shape jpad))

real-shape-jpad

shape-jpad

[procedure] (real-shape-jpad SHAPE DIMS [JUST-HORZ [JUST-VERT [CHARS]]]) -> real-shape-plotter
[procedure] (shape-jpad SHAPE DIMS [JUST-HORZ [JUST-VERT [CHARS]]])) -> shape-plotter

JUST-HORZ: {[symbol]} ; left | center | right
JUST-VERT: {[symbol]} ; top | center | bottom

Char Canvas Shape hgroup

Usage

(import (s9fes char-canvas shape hgroup))

real-shape-hgroup

shape-hgroup

[procedure] (real-shape-hgroup SHAPES | SHAPE ...) -> real-shape-plotter
[procedure] (shape-hgroup SHAPES | SHAPE ...) -> shape-plotter

SHAPES: (list-of shape) ; single-argument & a list
SHAPE ...: list-of shape ; single-argument & not a list or multi-argument

Char Canvas Shape vgroup

Usage

(import (s9fes char-canvas shape vgroup))

real-shape-vgroup

shape-vgroup

[procedure] (real-shape-vgroup SHAPES | SHAPE ...) -> real-shape-plotter
[procedure] (shape-vgroup SHAPES | SHAPE ...) -> shape-plotter

SHAPES: (list-of shape) ; single-argument & a list
SHAPE ...: list-of shape ; single-argument & not a list or multi-argument

Bugs & Limitations

None. A thing of beauty.

Notes

Shape position as the center is different. The lower-left is probably expected.
All shapes are justified (lay'ed out) or static, except jpad, hgroup, & vgroup. These will apportion available space in the layout bounding-box to the wrapped shapes, returning a new, static, shape.
The plot/virtual API with the draw/real distinction follows the original pattern. However, except as implementation details, using the draw/real is unlikely to be worth the effort. For performance have pixels always be chars: don't specify a virtual canvas size.

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

1.3.0: plotter-configuration change.
1.2.1: Fix .egg.
1.2.0: Add fpad, jpad, hgroup, vgroup.
1.1.0: Rename problematic cross symbols.
1.0.0: Move shapes from the s9fes-char-canvas) egg.

License

Public Domain