4 RRLL: Canvas

8.10

4 RRLL: Canvas

Dominik Pantůček <dominik.pantucek@trustica.cz>

Racket Rogue-Like Library: Drawing (A)RGB Canvas

This module re-provides all bindings from rrll/canvas/core, rrll/canvas/pixels, rrll/canvas/drawing, rrll/canvas/transform, rrll/canvas/bitmap and rrll/canvas/overlay.

4.1 Core Canvas

(require rrll/canvas/core)

package: rrll-canvas

Provides the raw canvas struct and its constructors.

struct
(struct canvas (width height data offset stride))
  width : fixnum?
  height : fixnum?
  data : fxvector?
  offset : fixnum?
  stride : fixnum?

Storage for canvas pixels.

procedure
(make-canvas w h) → canvas?
w : fixnum?
h : fixnum?

Creates new canvas of given size.

procedure
(make-sub-canvas c x y w h) → canvas?
  c : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?

Creates new canvas which is part of already existing canvas and shares the backing store with the original one.

4.2 Direct Pixel Access

(require rrll/canvas/pixels)

package: rrll-canvas

This module contains procedures for direct pixel access of the canvas. It is not intended for general use.

procedure
(canvas-putpixel! can x y color) → void?
  can : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum?

Changes given pixel to specified color. Handles clipping correctly.

procedure
(unsafe-canvas-putpixel! can x y color) → void?
  can : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum?

Changes given pixel to specified color without any clipping.

procedure
(canvas-getpixel can x y) → fixnum?
  can : canvas?
  x : fixnum?
  y : fixnum?

Gets pixel from given canvas. If a pixel outside the canvas is chosen, 0 is returned.

procedure
(unsafe-canvas-getpixel can x y) → fixnum?
  can : canvas?
  x : fixnum?
  y : fixnum?

Gets pixel from given canvas. No bounds checks are performed.

4.3 Canvas Drawing

(require rrll/canvas/drawing)

package: rrll-canvas

procedure
(draw-pixel dst x y [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum? = #xff000000

Draws a single pixel to canvas using given rgb color.

procedure
(draw-pixel/a dst x y [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum? = #xff000000

The same as draw-pixel but blending the ARGB color over current destination.

procedure
(draw-clear dst [color]) → void?
dst : canvas?
color : fixnum? = #xff000000

Clears canvas using specified color.

procedure
(draw-clear/a dst [color]) → void?
dst : canvas?
color : fixnum? = #xff000000

The same as draw-clear but blending the ARGB color over current destination.

procedure
(draw-bar dst x y w h [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  color : fixnum? = #xff000000

Fills rectangular bar with given color. Performs necessary clipping.

procedure
(draw-bar/a dst x y w h [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  color : fixnum? = #xff000000

The same as draw-bar but blending the ARGB color over current destination.

procedure
(draw-hline dst x y w [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  color : fixnum? = #xff000000

Draws a horizontal line using given color. Performs necessary clipping.

procedure
(draw-hline/a dst x y w [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  color : fixnum? = #xff000000

The same as draw-hline but blending the ARGB color over current destination.

procedure
(draw-vline dst x y h [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  h : fixnum?
  color : fixnum? = #xff000000

Draws a vertical line using given color. Performs any clipping necessary.

procedure
(draw-vline/a dst x y h [color]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  h : fixnum?
  color : fixnum? = #xff000000

The same as draw-vline but blending the ARGB color over current destination.

procedure
(draw-line dst x0 y0 x1 y1 [color]) → void?
  dst : canvas?
  x0 : fixnum?
  y0 : fixnum?
  x1 : fixnum?
  y1 : fixnum?
  color : fixnum? = #xff000000

Draws a line using Bresenham’s line-drawing algorithm using the color specified. Performs necessary clipping.

procedure
(draw-line/a dst x0 y0 x1 y1 [color]) → void?
  dst : canvas?
  x0 : fixnum?
  y0 : fixnum?
  x1 : fixnum?
  y1 : fixnum?
  color : fixnum? = #xff000000

The same as draw-line but blending the ARGB color over current destination.

procedure
(draw-circle dst xc yc radius [color]) → void?
  dst : canvas?
  xc : fixnum?
  yc : fixnum?
  radius : fixnum?
  color : fixnum? = #xff000000

Draws a circle using Bresenham’s circle-drawing algorithm centered at the point xc, yc with given radius. Performs any clipping necessary.

procedure
(draw-circle/a dst xc yc radius [color]) → void?
  dst : canvas?
  xc : fixnum?
  yc : fixnum?
  radius : fixnum?
  color : fixnum? = #xff000000

The same as draw-circle but blending the ARGB color over current destination.

procedure
(fill-circle dst xc yc radius [color]) → void?
  dst : canvas?
  xc : fixnum?
  yc : fixnum?
  radius : fixnum?
  color : fixnum? = #xff000000

Fills a circle using Bresenham’s circle-drawing algorithm centered at the point xc, yc with given radius. Performs any clipping necessary.

procedure
(fill-circle/a dst xc yc radius [color]) → void?
  dst : canvas?
  xc : fixnum?
  yc : fixnum?
  radius : fixnum?
  color : fixnum? = #xff000000

The same as fill-circle but blending the ARGB color over current destination.

procedure
(fill-triangle dst x1 y1 x2 y2 x3 y3 [color]) → void?
  dst : canvas?
  x1 : fixnum?
  y1 : fixnum?
  x2 : fixnum?
  y2 : fixnum?
  x3 : fixnum?
  y3 : fixnum?
  color : fixnum? = #xff000000

Fills a triangle specified by the three points’ coordinates. Performs any clipping necessary.

procedure
(fill-triangle/a dst x1 y1 x2 y2 x3 y3 [color]) → void?
  dst : canvas?
  x1 : fixnum?
  y1 : fixnum?
  x2 : fixnum?
  y2 : fixnum?
  x3 : fixnum?
  y3 : fixnum?
  color : fixnum? = #xff000000

The same as fill-triangle but blending the ARGB color over current destination.

procedure
(fill-flood dst x y [color #:wrap? wrap?]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum? = 4278190080
  wrap? : boolean? = #f

Flood-fill with given color starting at given coordinates wrapping around if wrap? is #t.

procedure
(fill-flood/a dst x y [color #:wrap? wrap?]) → void?
  dst : canvas?
  x : fixnum?
  y : fixnum?
  color : fixnum? = 4278190080
  wrap? : boolean? = #f

The same as fill-flood but blending the ARGB color over current destination.

4.4 Transformations

(require rrll/canvas/transform)

package: rrll-canvas

Full-canvas transformations.

procedure
(canvas-transpose! dst src) → void?
dst : canvas?
src : canvas?

Transpose given src into dst. The source width must be the same as destination height and vice-versa.

procedure
(canvas-downscale! dst src [sw sh]) → void?
  dst : canvas?
  src : canvas?
  sw : boolean? = #t
  sh : boolean? = #t

Downcales given source canvas to the destination one by width if sw is #t and/or by height if sh is #t.

4.5 Bitmap Saving and Loading

(require rrll/canvas/bitmap)

package: rrll-canvas

Procedures for canvas saving into JPEG or PNG images and loading from any file type supported by racket/draw.

procedure
(load-bitmap filename-or-data) → canvas?
filename-or-data : (or/c string? bytes?)

Loads given file or image data into a canvas?.

procedure
(canvas->bitmap% can) → (is-a?/c bitmap%)
can : canvas?

Converts given canvas to racket/draw bitmap%.

procedure
(save-bitmap canvas filename) → void?
canvas : canvas?
filename : string?

Saves given canvas? into specified filename. The file extension must be either ".png", ".jpg" or ".jpeg".

4.6 Mipmapping

(require rrll/mipmap/core)

package: rrll-canvas

Special canvas extension to allow anisotropic sampling for high-quality downscaling and texturing.

struct
(struct mipmap canvas ( log2width
log2height
w-offsets
h-offsets
mmwidth:fl
mmheight:fl
row-shift))
  log2width : fixnum?
  log2height : fixnum?
  w-offsets : fxvector?
  h-offsets : fxvector?
  mmwidth:fl : flonum?
  mmheight:fl : flonum?
  row-shift : fixnum?

Holds the extended canvas containing all mipmaps required. Both its width and height is twice the original with the last pixel in both dimensions unused.

4.6.1 Mipmap Construction

(require rrll/mipmap/build)

package: rrll-canvas

procedure
(canvas->mipmap can) → mipmap?
can : canvas?

Creates a mipmap from canvas. The source dimensions must both be a power of 2.

4.7 Advanced Sampling

(require rrll/canvas/sampling)

package: rrll-canvas

This module contains methods for direct bilinear sampling of canvas? structs - useful mainly for upscaling.

procedure
(canvas-sample u v) → fixnum?
u : flonum?
v : flonum?

Performs bilinear sampling on given canvas. The u and v coordinates are in canvas space ranging from 0 to the width and height of the canvas.

If the coordinates are outide of canvas range, they are interpreted as if the canvas was infinitely repeated in both vertical and horizontal directions.

procedure
(canvas-sample/a u v) → fixnum?
u : flonum?
v : flonum?

The same as canvas-sample but interpolating the ARGB color instead of RGB.

4.8 Advanced Mipmap Sampling

(require rrll/mipmap/sampling)

package: rrll-canvas

This moduel contains methods for trilinear/quadrilinear anisotropic sampling of mipmap? canvas extensions.

procedure
(mipmap-sample tw th u v) → fixnum?
  tw : flonum?
  th : flonum?
  u : flonum?
  v : flonum?

Performs bilinear/trilinear/quadrilinear sampling of given mipmap based on requested tw and th dimensions and the u and v coordinates.

If the coordinates are outside the mipmap, the sampled coordinates are wrapped around in both directions.

procedure
(mipmap-sample/a tw th u v) → fixnum?
  tw : flonum?
  th : flonum?
  u : flonum?
  v : flonum?

The same as mipmap-sample but interpolating the ARGB color instead of RGB.

procedure
(mipmap-sample-quad tw
th
u00
v00
u01
v01
u10
v10
u11
v11) →
fixnum? fixnum? fixnum? fixnum?
  tw : flonum?
  th : flonum?
  u00 : flonum?
  v00 : flonum?
  u01 : flonum?
  v01 : flonum?
  u10 : flonum?
  v10 : flonum?
  u11 : flonum?
  v11 : flonum?

Samples four texels at once.

procedure
(mipmap-sample-quad/a tw
th
u00
v00
u01
v01
u10
v10
u11
v11) →
fixnum? fixnum? fixnum? fixnum?
  tw : flonum?
  th : flonum?
  u00 : flonum?
  v00 : flonum?
  u01 : flonum?
  v01 : flonum?
  u10 : flonum?
  v10 : flonum?
  u11 : flonum?
  v11 : flonum?

The same as mipmap-sample-quad but interpolating the ARGB color instead of RGB.

4.9 Canvas Overlays

(require rrll/canvas/overlay)

package: rrll-canvas

procedure
(draw-canvas dst src [dx dy sx sy sw sh]) → void?
  dst : canvas?
  src : canvas?
  dx : fixnum? = 0
  dy : fixnum? = 0
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

Draws src into the backing canvas? at position (dx dy) performing any clipping required.

procedure
(draw-canvas/a dst src [dx dy sx sy sw sh]) → void?
  dst : canvas?
  src : canvas?
  dx : fixnum? = 0
  dy : fixnum? = 0
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as draw-canvas but blending the ARGB color over current destination.

procedure
(draw-canvas/b alpha dst src [dx dy sx sy sw sh]) → void?
  alpha : fixnum?
  dst : canvas?
  src : canvas?
  dx : fixnum? = 0
  dy : fixnum? = 0
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as draw-canvas but blending with alpha over current destination.

procedure
(draw-canvas/a/b alpha dst src [dx dy sx sy sw sh]) → void?
  alpha : fixnum?
  dst : canvas?
  src : canvas?
  dx : fixnum? = 0
  dy : fixnum? = 0
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as draw-canvas but blending with alpha combined with alpha channel from source ARGB over current destination.

procedure
(scale-canvas dst src x y w h [sx sy sw sh]) → void?
  dst : canvas?
  src : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

Draws src into the backing canvas? at position (x y) scaled to w\timesh performing any clipping required.

procedure
(scale-canvas/a dst src x y w h [sx sy sw sh]) → void?
  dst : canvas?
  src : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as scale-canvas but blending the ARGB color over current destination.

procedure
(scale-canvas/b alpha dst src x y w h [sx sy sw sh]) → void?
  alpha : fixnum?
  dst : canvas?
  src : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as scale-canvas but blending with alpha over current destination.

procedure
(scale-canvas/a/b alpha dst src x y w h [sx sy sw sh]) → void?
  alpha : fixnum?
  dst : canvas?
  src : canvas?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  sx : fixnum? = 0
  sy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f

The same as scale-canvas but blending with alpha combined with alpha channel from source ARGB over current destination.

4.10 Mipmap Overlays

(require rrll/mipmap/overlay)

package: rrll-canvas

procedure
(scale-mipmap dst src dx dy dw dh) → void?
  dst : canvas?
  src : mipmap?
  dx : fixnum?
  dy : fixnum?
  dw : fixnum?
  dh : fixnum?

Draws src into the backing canvas? at position (dx dy) scaled to dw\timesdh performing any clipping required.

procedure
(scale-mipmap/a dst src dx dy dw dh) → void?
  dst : canvas?
  src : mipmap?
  dx : fixnum?
  dy : fixnum?
  dw : fixnum?
  dh : fixnum?

The same as scale-mipmap but blending the ARGB color over current destination.

procedure
(scale-mipmap/b alpha dst src dx dy dw dh) → void?
  alpha : fixnum?
  dst : canvas?
  src : mipmap?
  dx : fixnum?
  dy : fixnum?
  dw : fixnum?
  dh : fixnum?

The same as scale-mipmap but blending with alpha over current destination.

procedure
(scale-mipmap/a/b alpha dst src dx dy dw dh) → void?
  alpha : fixnum?
  dst : canvas?
  src : mipmap?
  dx : fixnum?
  dy : fixnum?
  dw : fixnum?
  dh : fixnum?

The same as scale-mipmap but blending with alpha combined with alpha channel from source ARGB over current destination.

4.11 Canvas Syntax Definers

(require rrll/canvas/syntax)

package: rrll-canvas

This module provides utility syntaxes for defining multiple variants of procedures that work with canvas?.

syntax
(define/provide-draw [#:b] (name dst args ...) body ...)

Defines a procedure that draws something onto dst. The plain RGB variant name is defined and ARGB blending variant name/a is created as well.

The procedure body must do the actual drawing using the following procedure provided as local binding:

procedure
(draw doff sc) → void?
doff : fixnum?
sc : fixnum?

Draws a single pixel to destination canvas, possibly performing any source to destination blending required.

The source of the pixel color to be painted may be a constant color or color sampled from some resource like canvas? or mipmap?.

With the #:b keyword argument more functions are created: Plain RGB variant with explicit alpha value name/b and ARGB blending variant with explicit alpha value on top name/a/b.

Also, within the body the linear and bilinear identifiers are bound to either rgb-linear and rgb-bilinear or argb-linear and argb-bilinear as needed by particular drawing variant.

syntax
(define/provide-sampler (name can ...) body ...)

Defines two sampler variants one name for plain RGB sampling and another name/a for ARGB sampling.

Within the body the linear and bilinear identifiers are bound to either rgb-linear and rgb-bilinear or argb-linear and argb-bilinear as needed by particular sampling variant.

Note: This is an internal syntax form.

4.12 Querying Canvas Properties

(require rrll/canvas/query)

package: rrll-canvas

This module can infer canvas properties based on its contents.

procedure
(canvas-alpha? can) → boolean?
can : canvas?

Returns true if given canvas? contains one or more pixels with alpha value less than 255.

contents ← prev up next →

1	RRLL: Actor Basic 2.0
2	RRLL: ANSI Buffers
3	RRLL: Abuf Canvas
4	RRLL: Canvas
5	RRLL: Rendering Canvas
6	RRLL: Color Support
7	RRLL: Single-Channel Flomaps
8	RRLL: Futures
9	RRLL: Functional Grids
10	RRLL: Helpers
11	RRLL: Math
12	RRLL: Mutable Future Queue
13	RRLL: Rasterizer
14	RRLL: Renderer
15	RRLL: Terminal I/ O
16	RRLL: Ticker
17	RRLL: Unsafe

4.1	Core Canvas
4.2	Direct Pixel Access
4.3	Canvas Drawing
4.4	Transformations
4.5	Bitmap Saving and Loading
4.6	Mipmapping
4.7	Advanced Sampling
4.8	Advanced Mipmap Sampling
4.9	Canvas Overlays
4.10	Mipmap Overlays
4.11	Canvas Syntax Definers
4.12	Querying Canvas Properties