From 3d0d6d981ba65fb1cb93e67c40cbbac329d3fb9c Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sat, 5 Dec 2020 20:32:34 -0500 Subject: doc: Reorganize graphics section. --- doc/api.texi | 500 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 250 insertions(+), 250 deletions(-) (limited to 'doc') diff --git a/doc/api.texi b/doc/api.texi index aed1b00..e9aa72f 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -1584,10 +1584,10 @@ blocks to implement additional rendering techniques. * Colors:: Such pretty colors... * Textures:: 2D images. * Sprites:: Draw 2D images. -* Tile Maps:: Draw 2D tile maps. -* Vector Paths:: Draw filled and stroked paths. * Fonts:: Drawing text. +* Vector Paths:: Draw filled and stroked paths. * Particles:: Pretty little flying pieces! +* Tile Maps:: Draw 2D tile maps. * 3D Models:: Spinning teapots everywhere. * Blending:: Control how pixels are combined. * Framebuffers:: Render to texture. @@ -2083,204 +2083,79 @@ Refer to @code{draw-sprite} (@pxref{Sprites}) for information about the other arguments. @end deffn -@node Tile Maps -@subsection Tile Maps - -A tile map is a scene created by composing lots of small sprites, -called ``tiles'', into a larger image. One program for editing such -maps is called @url{http://mapeditor.org,Tiled}. Chickadee has native -support for loading and rendering Tiled maps in the @code{(chickadee -graphics tiled)} module. - -@deffn {Procedure} load-tile-map file-name -Load the Tiled formatted map in @var{file-name} and return a new tile -map object. -@end deffn - -@deffn {Procedure} tile-map? obj -Return @code{#t} if @var{obj} is a tile map. -@end deffn - -@deffn {Procedure} tile-map-orientation tile-map -Return the orientation of @var{tile-map}. -@end deffn - -@deffn {Procedure} tile-map-width tile-map -Return the width of @var{tile-map} in tiles. -@end deffn - -@deffn {Procedure} tile-map-height tile-map -Return the height of @var{tile-map} in tiles. -@end deffn - -@deffn {Procedure} tile-map-tile-width tile-map -Return the width of tiles in @var{tile-map}. -@end deffn - -@deffn {Procedure} tile-map-tile-height tile-map -Return the height of tiles in @var{tile-map}. -@end deffn - -@deffn {Procedure} tile-map-tilesets tile-map -Return the tilesets for @var{tile-map}. -@end deffn - -@deffn {Procedure} tile-map-layers tile-map -Return the layers of @var{tile-map}. -@end deffn - -@deffn {Procedure} tile-map-properties tile-map -Return the custom properties of @var{tile-map}. -@end deffn - -@deffn {Procedure} point->tile tile-map x y -Translate the pixel coordinates (@var{x}, @var{y}) into tile -coordinates. -@end deffn - -@deffn {Procedure} draw-tile-map tile-map [#:layers] [#:camera] @ - [#:origin] [#:position] [#:scale] [#:rotation] - -Draw the layers of @var{tile-map} as viewed from @var{camera}, a 2D -vector offset. By default, all layers are drawn. To draw a subset of -the available layers, pass a list of layer ids using the @var{layers} -keyword argument. -@end deffn - -@deffn {Procedure} tileset? obj -Return @code{#t} if @var{obj} is a tileset. -@end deffn - -@deffn {Procedure} tileset-name tileset -Return the name of @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-first-gid tileset -Return the starting GID of @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-size tileset -Return the number of tiles in @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-tile-width tileset -Return the width of tiles in @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-tile-height tileset -Return the height of tiles in @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-atlas tileset -Return the texture atlas for @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-tiles tileset -Return the tiles in @var{tileset}. -@end deffn - -@deffn {Procedure} tileset-properties tileset -Return the custom properties of @var{tileset}. -@end deffn - -@deffn {Procedure} tile? obj -Return @code{#t} if @var{obj} is a tile. -@end deffn - -@deffn {Procedure} tile-id tile -Return the ID of @var{tile}. -@end deffn - -@deffn {Procedure} tile-animation tile -Return the animation for @var{tile}. -@end deffn - -@deffn {Procedure} tile-properties tile -Return the custom properties of @var{tile}. -@end deffn - -@deffn {Procedure} animation-frame? obj -Return @code{#t} if @var{obj} is an animation frame. -@end deffn - -@deffn {Procedure} animation-frame-tile frame -Return the tile for @var{frame}. -@end deffn - -@deffn {Procedure} animation-frame-duration frame -Return the duration of @var{frame}. -@end deffn - -@deffn {Procedure} tile-layer? obj -Return @code{#t} if @var{obj} is a tile layer. -@end deffn +@node Fonts +@subsection Fonts -@deffn {Procedure} tile-layer-name layer -Return the name of @var{layer}. -@end deffn +Printing text to the screen is quite easy: -@deffn {Procedure} tile-layer-width layer -Return the width in tiles of @var{layer}. -@end deffn +@example +(draw-text "Hello, world" (vec2 100.0 100.0)) +@end example -@deffn {Procedure} tile-layer-height layer -Return the height in tiles of @var{layer}. -@end deffn +Chickadee supports OpenType/TrueType fonts (via the FreeType library), +bitmap fonts in Angel Code bmfont format, and simple sprite sheet +bitmap fonts. A default font named Inconsolata is used for all text +rendering operations where a font is not specified, as is the case in +the above example. -@deffn {Procedure} tile-layer-tiles layer -Return the tile data for @var{layer}. -@end deffn +The following procedures can be found in the @code{(chickadee graphics +font)} module: -@deffn {Procedure} tile-layer-properties layer -Return the custom properties of @var{layer}. +@deffn {Procedure} load-font file-name point-size [#:char-set] +Load the scalable (OpenType, TrueType, etc.) font in the file +@var{file-name} and display it at the given @var{point-size}. By +default, all the characters in the ASCII character set are loaded. +This can be changed by passing a different character set +(@pxref{Character Sets,,, guile, GNU Guile Reference Manual}) using +the @var{char-set} keyword argument. @end deffn -@deffn {Procedure} object-layer? obj -Return @code{#t} if @var{obj} is an object layer. +@deffn {Procedure} load-bitmap-font file +Load the Angel Code font (in either XML or FNT format) in @var{file} +and return a new font object. @end deffn -@deffn {Procedure} object-layer-name layer -Return the name of @var{layer}. +@deffn {Procedure} font? obj +Return @code{#t} if @var{obj} is a font object. @end deffn -@deffn {Procedure} object-layer-objects layer -Return the objects for @var{layer}. +@deffn {Procedure} font-face font +Return the name of @var{font}. @end deffn -@deffn {Procedure} object-layer-properties layer -Return the custom properties of @var{layer}. +@deffn {Procedure} font-line-height font +Return the line height of @var{font}. @end deffn -@deffn {Procedure} map-object? obj -Return @code{#t} if @var{obj} is a map object. +@deffn {Procedure} font-line-height font +Return the line height of @var{font}. @end deffn -@deffn {Procedure} map-object-id obj -Return the ID of @var{obj}. +@deffn {Procedure} font-bold? font +Return @code{#t} if @var{font} is a bold font. @end deffn -@deffn {Procedure} map-object-name obj -Return the name of @var{obj}. +@deffn {Procedure} font-italic? font +Return @code{#t} if @var{font} is an italicized font. @end deffn -@deffn {Procedure} map-object-type obj -Return the type of @var{obj}. -@end deffn +@deffn {Procedure} draw-text text position + [#:font] [#:color] [#:origin] [#:scale] [#:rotation] [#:blend-mode] + [#:start 0] [#:end @code{(string-length text)}] -@deffn {Procedure} map-object-shape obj -Return the shape of @var{obj}. -@end deffn +Draw the string @var{text} with the first character starting at +@var{position} using @var{font}. If @var{font} is not specified, a +built-in font is used. -@deffn {Procedure} map-object-properties obj -Return the custom properties of @var{obj}. -@end deffn +@example +(draw-text "Hello, world!" (vec2 128.0 128.0)) +@end example -@deffn {Procedure} polygon? obj -Return @code{#t} if @var{obj} is a polygon. -@end deffn +To render a substring of @var{text}, use the @var{start} and @var{end} +arguments. -@deffn {Procedure} polygon-points polygon -Return the list of points that form @var{polygon}. +Refer to @code{draw-sprite} (@pxref{Sprites}) for information about +the other arguments. @end deffn @node Vector Paths @@ -2497,81 +2372,6 @@ Set the 3x3 transformation matrix of @var{canvas} to @var{matrix}. Render @var{canvas} to the screen. @end deffn -@node Fonts -@subsection Fonts - -Printing text to the screen is quite easy: - -@example -(draw-text "Hello, world" (vec2 100.0 100.0)) -@end example - -Chickadee supports OpenType/TrueType fonts (via the FreeType library), -bitmap fonts in Angel Code bmfont format, and simple sprite sheet -bitmap fonts. A default font named Inconsolata is used for all text -rendering operations where a font is not specified, as is the case in -the above example. - -The following procedures can be found in the @code{(chickadee graphics -font)} module: - -@deffn {Procedure} load-font file-name point-size [#:char-set] -Load the scalable (OpenType, TrueType, etc.) font in the file -@var{file-name} and display it at the given @var{point-size}. By -default, all the characters in the ASCII character set are loaded. -This can be changed by passing a different character set -(@pxref{Character Sets,,, guile, GNU Guile Reference Manual}) using -the @var{char-set} keyword argument. -@end deffn - -@deffn {Procedure} load-bitmap-font file -Load the Angel Code font (in either XML or FNT format) in @var{file} -and return a new font object. -@end deffn - -@deffn {Procedure} font? obj -Return @code{#t} if @var{obj} is a font object. -@end deffn - -@deffn {Procedure} font-face font -Return the name of @var{font}. -@end deffn - -@deffn {Procedure} font-line-height font -Return the line height of @var{font}. -@end deffn - -@deffn {Procedure} font-line-height font -Return the line height of @var{font}. -@end deffn - -@deffn {Procedure} font-bold? font -Return @code{#t} if @var{font} is a bold font. -@end deffn - -@deffn {Procedure} font-italic? font -Return @code{#t} if @var{font} is an italicized font. -@end deffn - -@deffn {Procedure} draw-text text position - [#:font] [#:color] [#:origin] [#:scale] [#:rotation] [#:blend-mode] - [#:start 0] [#:end @code{(string-length text)}] - -Draw the string @var{text} with the first character starting at -@var{position} using @var{font}. If @var{font} is not specified, a -built-in font is used. - -@example -(draw-text "Hello, world!" (vec2 128.0 128.0)) -@end example - -To render a substring of @var{text}, use the @var{start} and @var{end} -arguments. - -Refer to @code{draw-sprite} (@pxref{Sprites}) for information about -the other arguments. -@end deffn - @node Particles @subsection Particles @@ -2719,6 +2519,206 @@ Add @var{emitter} to @var{particles}. Remove @var{emitter} to @var{particles} @end deffn +@node Tile Maps +@subsection Tile Maps + +A tile map is a scene created by composing lots of small sprites, +called ``tiles'', into a larger image. One program for editing such +maps is called @url{http://mapeditor.org,Tiled}. Chickadee has native +support for loading and rendering Tiled maps in the @code{(chickadee +graphics tiled)} module. + +@deffn {Procedure} load-tile-map file-name +Load the Tiled formatted map in @var{file-name} and return a new tile +map object. +@end deffn + +@deffn {Procedure} tile-map? obj +Return @code{#t} if @var{obj} is a tile map. +@end deffn + +@deffn {Procedure} tile-map-orientation tile-map +Return the orientation of @var{tile-map}. +@end deffn + +@deffn {Procedure} tile-map-width tile-map +Return the width of @var{tile-map} in tiles. +@end deffn + +@deffn {Procedure} tile-map-height tile-map +Return the height of @var{tile-map} in tiles. +@end deffn + +@deffn {Procedure} tile-map-tile-width tile-map +Return the width of tiles in @var{tile-map}. +@end deffn + +@deffn {Procedure} tile-map-tile-height tile-map +Return the height of tiles in @var{tile-map}. +@end deffn + +@deffn {Procedure} tile-map-tilesets tile-map +Return the tilesets for @var{tile-map}. +@end deffn + +@deffn {Procedure} tile-map-layers tile-map +Return the layers of @var{tile-map}. +@end deffn + +@deffn {Procedure} tile-map-properties tile-map +Return the custom properties of @var{tile-map}. +@end deffn + +@deffn {Procedure} point->tile tile-map x y +Translate the pixel coordinates (@var{x}, @var{y}) into tile +coordinates. +@end deffn + +@deffn {Procedure} draw-tile-map tile-map [#:layers] [#:camera] @ + [#:origin] [#:position] [#:scale] [#:rotation] + +Draw the layers of @var{tile-map} as viewed from @var{camera}, a 2D +vector offset. By default, all layers are drawn. To draw a subset of +the available layers, pass a list of layer ids using the @var{layers} +keyword argument. +@end deffn + +@deffn {Procedure} tileset? obj +Return @code{#t} if @var{obj} is a tileset. +@end deffn + +@deffn {Procedure} tileset-name tileset +Return the name of @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-first-gid tileset +Return the starting GID of @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-size tileset +Return the number of tiles in @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-tile-width tileset +Return the width of tiles in @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-tile-height tileset +Return the height of tiles in @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-atlas tileset +Return the texture atlas for @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-tiles tileset +Return the tiles in @var{tileset}. +@end deffn + +@deffn {Procedure} tileset-properties tileset +Return the custom properties of @var{tileset}. +@end deffn + +@deffn {Procedure} tile? obj +Return @code{#t} if @var{obj} is a tile. +@end deffn + +@deffn {Procedure} tile-id tile +Return the ID of @var{tile}. +@end deffn + +@deffn {Procedure} tile-animation tile +Return the animation for @var{tile}. +@end deffn + +@deffn {Procedure} tile-properties tile +Return the custom properties of @var{tile}. +@end deffn + +@deffn {Procedure} animation-frame? obj +Return @code{#t} if @var{obj} is an animation frame. +@end deffn + +@deffn {Procedure} animation-frame-tile frame +Return the tile for @var{frame}. +@end deffn + +@deffn {Procedure} animation-frame-duration frame +Return the duration of @var{frame}. +@end deffn + +@deffn {Procedure} tile-layer? obj +Return @code{#t} if @var{obj} is a tile layer. +@end deffn + +@deffn {Procedure} tile-layer-name layer +Return the name of @var{layer}. +@end deffn + +@deffn {Procedure} tile-layer-width layer +Return the width in tiles of @var{layer}. +@end deffn + +@deffn {Procedure} tile-layer-height layer +Return the height in tiles of @var{layer}. +@end deffn + +@deffn {Procedure} tile-layer-tiles layer +Return the tile data for @var{layer}. +@end deffn + +@deffn {Procedure} tile-layer-properties layer +Return the custom properties of @var{layer}. +@end deffn + +@deffn {Procedure} object-layer? obj +Return @code{#t} if @var{obj} is an object layer. +@end deffn + +@deffn {Procedure} object-layer-name layer +Return the name of @var{layer}. +@end deffn + +@deffn {Procedure} object-layer-objects layer +Return the objects for @var{layer}. +@end deffn + +@deffn {Procedure} object-layer-properties layer +Return the custom properties of @var{layer}. +@end deffn + +@deffn {Procedure} map-object? obj +Return @code{#t} if @var{obj} is a map object. +@end deffn + +@deffn {Procedure} map-object-id obj +Return the ID of @var{obj}. +@end deffn + +@deffn {Procedure} map-object-name obj +Return the name of @var{obj}. +@end deffn + +@deffn {Procedure} map-object-type obj +Return the type of @var{obj}. +@end deffn + +@deffn {Procedure} map-object-shape obj +Return the shape of @var{obj}. +@end deffn + +@deffn {Procedure} map-object-properties obj +Return the custom properties of @var{obj}. +@end deffn + +@deffn {Procedure} polygon? obj +Return @code{#t} if @var{obj} is a polygon. +@end deffn + +@deffn {Procedure} polygon-points polygon +Return the list of points that form @var{polygon}. +@end deffn + @node 3D Models @subsection 3D Models -- cgit v1.2.3