From efb13bfd786b58179713e81f70497e0c01a498e1 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Mon, 9 Nov 2015 22:16:21 -0500 Subject: Update documentation a bit. --- doc/api/init.texi | 1 + doc/api/input.texi | 2 +- doc/api/math.texi | 24 ++++++++++---------- doc/api/rendering.texi | 57 ++++++++++++++++++++++++++++++++++++----------- doc/api/signals.texi | 5 +++-- doc/sly.texi | 60 +++++++++++++++++++++++--------------------------- 6 files changed, 88 insertions(+), 61 deletions(-) diff --git a/doc/api/init.texi b/doc/api/init.texi index 14eff4b..7060d1d 100644 --- a/doc/api/init.texi +++ b/doc/api/init.texi @@ -15,6 +15,7 @@ Sly uses the windowing features of SDL 1.2 under the hood, which currently restricts Sly applications to using only a single window. +SDL2 support will come in a future release. The window data structure: diff --git a/doc/api/input.texi b/doc/api/input.texi index 3a4e6a3..02a42d0 100644 --- a/doc/api/input.texi +++ b/doc/api/input.texi @@ -8,7 +8,7 @@ events (@pxref{Signals}). @menu * Keyboard:: Clack clack. * Mouse:: Exercise the rodent. -* Joystick:: Wee! +* Joystick:: Arcade-style fun. @end menu @node Keyboard diff --git a/doc/api/math.texi b/doc/api/math.texi index 8102e04..9582ea7 100644 --- a/doc/api/math.texi +++ b/doc/api/math.texi @@ -159,23 +159,23 @@ dimensions (@var{width}, @var{height}). Rectangle with @code{x}, @code{y}, @code{width}, and @code{height} of 0. @end defvr -@deffn {Scheme Macro} rect? @var{obj} +@deffn {Scheme Syntax} rect? @var{obj} Return @code{#t} if @var{obj} is a rectangle. @end deffn -@deffn {Scheme Macro} rect-x @var{rect} +@deffn {Scheme Syntax} rect-x @var{rect} Return the x coordinate of @var{rect}. @end deffn -@deffn {Scheme Macro} rect-y @var{rect} +@deffn {Scheme Syntax} rect-y @var{rect} Return the x coordinate of @var{rect}. @end deffn -@deffn {Scheme Macro} rect-width @var{rect} +@deffn {Scheme Syntax} rect-width @var{rect} Return the width of @var{rect}. @end deffn -@deffn {Scheme Macro} rect-height @var{rect} +@deffn {Scheme Syntax} rect-height @var{rect} Return the height of @var{rect}. @end deffn @@ -311,11 +311,11 @@ A transform composed entirely of zeroes. The multiplicative identity transform. @end defvr -@deffn {Scheme Macro} transform? @var{obj} +@deffn {Scheme Syntax} transform? @var{obj} Return @code{#t} if @var{obj} is a transform. @end deffn -@deffn {Scheme Macro} transform-matrix @var{transform} +@deffn {Scheme Syntax} transform-matrix @var{transform} Return the underlying 4x4 floating point array for @var{transform}. @end deffn @@ -527,23 +527,23 @@ an angle @var{theta}) or from individual coordinates @var{w}, @var{x}, Alternate spelling of @code{make-quaternion}. @end deffn -@deffn {Scheme Macro} quaternion? @var{obj} +@deffn {Scheme Syntax} quaternion? @var{obj} Return @code{#t} if @var{obj} is a quaternion. @end deffn -@deffn {Scheme Macro} quaternion-w @var{q} +@deffn {Scheme Syntax} quaternion-w @var{q} Return the w coordinate of the quaternion @var{q}. @end deffn -@deffn {Scheme Macro} quaternion-x @var{q} +@deffn {Scheme Syntax} quaternion-x @var{q} Return the x coordinate of the quaternion @var{q}. @end deffn -@deffn {Scheme Macro} quaternion-y @var{q} +@deffn {Scheme Syntax} quaternion-y @var{q} Return the y coordinate of the quaternion @var{q}. @end deffn -@deffn {Scheme Macro} quaternion-z @var{q} +@deffn {Scheme Syntax} quaternion-z @var{q} Return the z coordinate of the quaternion @var{q}. @end deffn diff --git a/doc/api/rendering.texi b/doc/api/rendering.texi index 364d09c..236863d 100644 --- a/doc/api/rendering.texi +++ b/doc/api/rendering.texi @@ -1,8 +1,14 @@ @node Rendering @section Rendering +Keeping with the theme of declarative and functional code, Sly's +rendering module provide a purely functional interface to the +imperative world of OpenGL. An abstraction on top of OpenGL known as +``render combinators'' provide a convenient way to describe and +compose rendering pipelines. + @menu -* Scene Graph:: Declarative rendering. +* Render Combinators:: Purely functional rendering API. * Sprites:: 2D textured rectangles. * Textures:: Pixel arrays. * Fonts:: Font loading and text rendering. @@ -10,25 +16,47 @@ * Cameras:: Defining a viewpoint. * Colors:: Pretty colors. * Framebuffers:: Offscreen rendering. +* Shaders:: Programs that run on the GPU. @end menu -@node Scene Graph -@subsection Scene Graph - -@menu -* Models:: Renderable objects. -* Groups:: Transformation hierarchy. -@end menu - -@node Models -@subsubsection Models +@node Render Combinators +@subsection Render Combinators -@node Groups -@subsubsection Groups +Render combinators provide a purely functional interface to the OpenGL +state machine. @node Sprites @subsection Sprites +@deffn {Scheme Procedure} make-sprite @var{texture} [#:anchor] +Create a sprite that displays the image in @var{texture}. The size of +the mesh is the size of @var{texture} in pixels. @var{anchor} defines +the origin of the sprite. By default, the anchor is @code{center}, +which puts the origin in the middle of the sprite. See +'anchor-texture' for more anchoring options. +@end deffn + +@deffn {Scheme Procedure} load-sprite @var{file} [#:anchor] +Create a sprite from the texture in @var{file} whose origin is defined +by @var{anchor}. The default anchor is @code{center}. +@end deffn + +@deffn {Scheme Syntax} sprite? @var{obj} +Return @code{#t} if @var{obj} is a sprite. +@end deffn + +@deffn {Scheme Syntax} sprite-texture @var{sprite} +Return the texture for @var{sprite}. +@end deffn + +@deffn {Scheme Syntax} sprite-mesh @var{mesh} +Return the mesh for @var{sprite}. +@end deffn + +@deffn {Scheme Procedure} render-sprite @var{sprite} +Create a renderer for @var{sprite}. +@end deffn + @node Textures @subsection Textures @@ -46,3 +74,6 @@ @node Framebuffers @subsection Framebuffers + +@node Shaders +@subsection Shaders diff --git a/doc/api/signals.texi b/doc/api/signals.texi index 9f674e1..0d8c589 100644 --- a/doc/api/signals.texi +++ b/doc/api/signals.texi @@ -8,7 +8,7 @@ number of callback procedures are registered to respond to events which mutate the relevant data structures. However, this approach, while simple and effective, comes at the price of readability, reproducibility, and expression. Instead of explicitly mutating data -and entering ``callback hell'', Sly abstracts and formalizes the +and entering ``callback hell,'' Sly abstracts and formalizes the process using a functional reactive programming style. In Sly, time-varying values are called ``signals'', and they are @@ -34,7 +34,8 @@ player move faster. Finally, the scaled vector is added to the previous player position via @code{signal-fold}. The player's position is at (320, 240) initially. As you can see, there are no callbacks and explicit mutation needed, and the position seems to -magically change with the passage of time. +magically change with the passage of time and pushing of the arrow +keys. @deffn {Scheme Procedure} signal? @var{obj} Return @code{#t} if @var{obj} is a signal. diff --git a/doc/sly.texi b/doc/sly.texi index 8eaeb71..71a84cd 100644 --- a/doc/sly.texi +++ b/doc/sly.texi @@ -65,40 +65,34 @@ Scheme programming language. With the help of Guile, Sly provides all of the essential building blocks for making video games, such as: window management, input even handling, rendering, linear algebra, and powerful scripting capabilities. Sly differentiates itself from -traditional game engines by providing a dynamic live coding -environment, functional reactive programming, and a declarative scene -graph. - -Live coding is the practice of improvised interactive programming. -Sly provides a suitable environment for live coding by leveraging -Emacs, Geiser, and Guile's cooperative REPL server. With these tools, -programmers may evaluate arbitrary code and see the effects of their -modifications in real time. This tight feedback loop allows for -faster prototyping, greater productivity, and most importantly, more -fun. +traditional game engines by providing a dynamic live codinng +environment and a functional API. + +For those unfamiliar with the term, ``live coding'' is the practice of +improvised interactive programming. Sly provides a suitable +environment for live coding by leveraging Guile's cooperative REPL +server. When used with a powerful editing tool such as Emacs (with +the fantastic Geiser extension), programmers may evaluate arbitrary +code and see the effects of their modifications in real time. This +tight feedback loop allows for faster prototyping, greater +productivity, and most importantly, more fun. Functional reactive programming (FRP) is a technique used to model time-varying values with pure functions. A pure function is a -function that produces no side-effects, such as calling 'set!' on a -variable or writing to the contents of an array. Sly encapsulates -time-varying values in ``signals'', a high-level data structure for -controlling the flow of events. Unlike imperative event callbacks, -signals can easily be composed to form new signals. By modeling game -state with pure functions and immutable data, a game can be seen as a -function of time, in the mathematical sense. Constructing a game this -way allows for deterministic behavior that is easier to reason about -than the accumulation of side-effects seen in traditional game -engines. - -A scene graph is a data structure for positioning renderable objects -relative to one another. Child nodes inherit the transformations -applied to their parent, making it easy to move a large amount of -objects around as a group rather than individually. Sly's implements -a declarative scene graph API, which means that the programmer -describes @emph{what} to render, rather than @emph{how} to render it. - -These three major components form a powerful, high-level environment -for building video games. +function whose return value depends solely upon its arguments. They +also produce no side-effects, such as calling 'set!' on a variable or +writing to a file on disk. Sly encapsulates time-varying values in +``signals'', a high-level data structure for controlling the flow of +events. Unlike imperative event callbacks, signals can easily be +composed to form new signals. By modeling game state with pure +functions and immutable data, a game can be seen as a function of +time. To play the game is to ``fold'' (accumulate a result) over +time. Constructing a game this way allows for deterministic behavior +that is easier to reason about and test than the accumulation of +side-effects seen in traditional game engines. The signal interface +is also declarative, meaning that the programmer describes @emph{what} +the state of the world should be like at any given time, rather than +@emph{how} to get there. @node Installation @chapter Installation @@ -195,8 +189,8 @@ grow! Please get in touch with us on @code{#sly} on the Freenode IRC network. We welcome ideas, bug reports, patches, and anything that may be helpful to the project. -The git source code repository can be found on Gitorious at -@url{https://gitorious.org/sly/sly}. +The git source code repository can be found at +@url{https://git.dthompson.us/sly.git}. @node Copying This Manual @appendix Copying This Manual -- cgit v1.2.3