From e7d470e954d0a17ab1b2fe0065f46f78475272f9 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Wed, 8 Apr 2020 17:10:29 -0400 Subject: Add chickade 0.5.0 stuff. --- haunt.scm | 3 +- manuals/chickadee/3D-Models.html | 157 +++++++++ manuals/chickadee/API-Reference.html | 29 +- manuals/chickadee/Agendas.html | 47 +-- manuals/chickadee/Audio-Files.html | 221 ++++++++++++ manuals/chickadee/Audio.html | 129 +++++++ manuals/chickadee/Basics.html | 53 ++- manuals/chickadee/Bezier-Curves.html | 37 +- manuals/chickadee/Blending-and-Depth-Testing.html | 103 ------ manuals/chickadee/Blending.html | 23 +- manuals/chickadee/Buffers.html | 73 ++-- manuals/chickadee/Channels.html | 31 +- manuals/chickadee/Colors.html | 377 +++++++++++++++++++++ manuals/chickadee/Copying-This-Manual.html | 21 +- manuals/chickadee/Easings.html | 53 ++- manuals/chickadee/Fonts.html | 35 +- manuals/chickadee/Framebuffers.html | 29 +- .../chickadee/GNU-Free-Documentation-License.html | 30 +- manuals/chickadee/Graphics.html | 51 ++- manuals/chickadee/Grid.html | 47 +-- manuals/chickadee/Index.html | 260 +++++++++++--- manuals/chickadee/Input-Devices.html | 156 +++++++++ manuals/chickadee/Installation.html | 21 +- manuals/chickadee/Kernel.html | 331 +----------------- manuals/chickadee/Lines-and-Shapes.html | 25 +- manuals/chickadee/Live-Coding.html | 127 +++++++ manuals/chickadee/Math.html | 39 +-- manuals/chickadee/Matrices.html | 63 ++-- manuals/chickadee/Particles.html | 51 ++- manuals/chickadee/Path-Finding.html | 25 +- manuals/chickadee/Quaternions.html | 33 +- manuals/chickadee/Rectangles.html | 101 +++--- manuals/chickadee/Rendering-Engine.html | 51 ++- manuals/chickadee/Requirements.html | 22 +- manuals/chickadee/Scripting.html | 31 +- manuals/chickadee/Scripts.html | 39 +-- manuals/chickadee/Shaders.html | 201 ++++++++--- manuals/chickadee/Sources.html | 336 ++++++++++++++++++ manuals/chickadee/Sprites.html | 46 ++- manuals/chickadee/Textures.html | 60 ++-- manuals/chickadee/The-Environment.html | 152 +++++++++ manuals/chickadee/The-Game-Loop.html | 360 ++++++++++++++++++++ manuals/chickadee/The-Listener.html | 141 ++++++++ manuals/chickadee/Tile-Maps.html | 129 +++---- manuals/chickadee/Tweening.html | 21 +- manuals/chickadee/Vectors.html | 118 ++++--- manuals/chickadee/Vertex-Arrays.html | 103 ------ manuals/chickadee/Viewports.html | 35 +- manuals/chickadee/Window-Manipulation.html | 191 +++++++++++ manuals/chickadee/index.html | 146 ++++---- posts/2020-04-08-chickadee-0.5.0-released.md | 61 ++++ 51 files changed, 3467 insertions(+), 1557 deletions(-) create mode 100644 manuals/chickadee/3D-Models.html create mode 100644 manuals/chickadee/Audio-Files.html create mode 100644 manuals/chickadee/Audio.html delete mode 100644 manuals/chickadee/Blending-and-Depth-Testing.html create mode 100644 manuals/chickadee/Colors.html create mode 100644 manuals/chickadee/Input-Devices.html create mode 100644 manuals/chickadee/Live-Coding.html create mode 100644 manuals/chickadee/Sources.html create mode 100644 manuals/chickadee/The-Environment.html create mode 100644 manuals/chickadee/The-Game-Loop.html create mode 100644 manuals/chickadee/The-Listener.html delete mode 100644 manuals/chickadee/Vertex-Arrays.html create mode 100644 manuals/chickadee/Window-Manipulation.html create mode 100644 posts/2020-04-08-chickadee-0.5.0-released.md diff --git a/haunt.scm b/haunt.scm index 36cafe4..3baf246 100644 --- a/haunt.scm +++ b/haunt.scm @@ -579,7 +579,8 @@ Scheme.") "Guile-OpenGL >= 0.1.0") #:license "GNU GPLv3+" #:releases - `(("0.4.0" ,(date 2019 06 04)) + `(("0.5.0" ,(date 2020 04 08)) + ("0.4.0" ,(date 2019 06 04)) ("0.3.0" ,(date 2018 10 03)) ("0.2.0" ,(date 2017 01 26)) ("0.1.0" ,(date 2017 01 23))))) diff --git a/manuals/chickadee/3D-Models.html b/manuals/chickadee/3D-Models.html new file mode 100644 index 0000000..1e6d2ca --- /dev/null +++ b/manuals/chickadee/3D-Models.html @@ -0,0 +1,157 @@ + + + + + + +3D Models (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Graphics   [Contents][Index]

+
+
+

2.3.8 3D Models

+ +

Disclaimer: Chickadee is alpha software, but 3D model support is +even more alpha than that. There are many missing features in both +the model loading and rendering components, so set your expectations +accordingly! +

+

Chickadee can load and render 3D models in the classic OBJ and more +modern glTF 2.0 formats. +

+

Here’s some basic boilerplate to render a 3D model: +

+
+
(use-modules (chickadee)
+             (chickadee math)
+             (chickadee math matrix)
+             (chickadee render model))
+
+(define model #f)
+(define projection-matrix
+  (perspective-projection (/ pi 3.0) (/ 4.0 3.0) 0.1 500.0))
+;; Adjust these 2 matrices so that you can actually see the model.
+(define view-matrix (make-identity-matrix4))
+(define model-matrix (make-identity-matrix4))
+
+(define (load)
+  (set! model (load-obj "model.obj"))
+
+(define (draw alpha)
+  (with-projection projection-matrix
+    (with-depth-test #t
+      (draw-model model model-matrix view-matrix))))
+
+(run-game #:load load #:draw draw)
+
+ +
+
Procedure: load-obj file-name
+

Load the OBJ formatted model in file-name and return a 3D model +object. +

+

OBJ models are rendered using a Phong lighting model, which is a +work-in-progress. +

+ +
+
Procedure: load-gltf file-name
+

Load the glTF 2.0 formatted model in file-name and return a 3D +model object. +

+

glTF models are rendered using a physically based lighting model, +which is currently a stub to be implemented later. +

+ +
+
Procedure: model? obj
+

Return #t if obj is a 3D model. +

+ +
+
Procedure: draw-model model model-matrix view-matrix
+

Render model with the transformation matrices model-matrix +and view-matrix applied. +

+ + + + + + diff --git a/manuals/chickadee/API-Reference.html b/manuals/chickadee/API-Reference.html index 67d2be0..19e03cf 100644 --- a/manuals/chickadee/API-Reference.html +++ b/manuals/chickadee/API-Reference.html @@ -1,6 +1,6 @@ - - + API Reference (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Agendas (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). + + + +Audio Files (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Up: Audio   [Contents][Index]

+
+
+

2.4.1 Audio Files

+ +

Sound data is represented by a special <audio> data type that +stores not only the audio samples themselves, but metadata such as +sample rate, number of channels, and how many bits are used for each +sample. +

+
+
Procedure: load-audio file-name [#:mode static]
+

Load audio within file-name. The following file formats are +currently supported: +

+
    +
  • WAV +
  • MP3 +
  • Ogg Vorbis +
+ +

Audio files can be loaded in two different ways, as indicated by +mode: +

+
    +
  • static: +Load the entire audio file into memory. +
  • stream: +Load chunks of the audio file as needed. +
+ +

Generally speaking, sound effects don’t take up much space and should +be loaded statically, but music files are much larger and should use +streaming. Static loading is the default. +

+ +
+
Procedure: audio? obj
+

Return #t if obj is an audio object. +

+ +
+
Procedure: streaming-audio? audio
+

Return #t if audio uses stream loading. +

+ +
+
Procedure: static-audio?
+

Return #t if audio uses static loading. +

+ +
+
Procedure: audio-mode audio
+

Return the loading mode for audio, either static or +stream. +

+ +
+
Procedure: audio-duration audio
+

Return the duration of audio in seconds. +

+ +
+
Procedure: audio-bits-per-sample audio
+

Return the number of bits per sample in audio. +

+ +
+
Procedure: audio-channels audio
+

Return the number of channels in audio. +

+ +
+
Procedure: audio-sample-rate audio
+

Return the sample rate of audio. +

+ +
+
Procedure: audio-play audio [#:pitch 1.0] [#:volume 1.0] [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] [#:reference-distance 0.0] [#:rolloff-factor 1.0] [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] [#:cone-outer-angle] [#:position (vec3 0.0 0.0 0.0)] [#:velocity (vec3 0.0 0.0 0.0)] [#:direction (vec3 0.0 0.0 0.0)] [#:relative? #f]
+
+

Play audio. There are many, many knobs to tweak that will +affect the sound that comes out of the player’s speakers.: +

+
    +
  • pitch: +Pitch multiplier. The default value of 1.0 means no change in pitch. +
  • volume: +Volume multiplier. The default value of 1.0 means no change in volume. +
  • min-volume: +Minimum volume. +
  • max-volume: +Maximum volume. +
  • max-distance: +Used with the inverse clamped distance model (the default model) to +set the distance where there will no longer be any attenuation of the +source. +
  • reference-distance: +The distance where the volume for the audio would drop by half (before +being influenced by the rolloff factor or maximum distance.) +
  • rolloff-factor: +For slowing down or speeding up the rate of attenuation. The default +of 1.0 means no attenuation adjustment is made. +
  • cone-outer-volume: +The volume when outside the oriented cone. +
  • cone-inner-angle: +Inner angle of the sound cone, in radians. The default value is 0. +
  • cone-outer-angle: +Outer angle of the sound cone, in radians. The default value is 2pi +radians, or 360 degrees. +
  • position: +The source of the sound emitter in 3D space. +
  • velocity: +The velocity of the sound emitter in 3D space. +
  • direction: +The direction of the sound emitter in 3D space. +
  • relative?: +A flag that determines whether the position is in absolute coordinates +or relative to the listener’s location. Absolute coordinates are used +by default. +
+ +

For games with basic sound needs (that is to say they don’t need 3D +sound modeling), the only things that really matter are volume +and pitch. +

+
+ +
+
+

+Next: , Up: Audio   [Contents][Index]

+
+ + + + + diff --git a/manuals/chickadee/Audio.html b/manuals/chickadee/Audio.html new file mode 100644 index 0000000..5540e83 --- /dev/null +++ b/manuals/chickadee/Audio.html @@ -0,0 +1,129 @@ + + + + + + +Audio (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: API Reference   [Contents][Index]

+
+
+

2.4 Audio

+ +

A game isn’t complete without sound. Most games play some cool +background music to set the mood and have many sound effects to play +when events happen. The (chickadee audio) module provides a +robust audio API backed by the OpenAL 3D audio system. +

+ + + + + +
• Audio Files  Not audiophiles. +
• Sources  Audio emitters. +
• The Listener  The player’s ears. +
• The Environment  Global sound model settings. +
+ +

The basics of playing audio are very simple. Just load an audio file +in the load hook (or anywhere else once the game loop is running) and +play it! +

+
+
(use-modules (chickadee audio))
+
+(define audio #f)
+
+(define (load)
+  (set! audio (load-audio "neat-sound-effect.wav"))
+  (audio-play audio))
+
+(run-game #:load load)
+
+ +

For more advanced usage, check out the full API reference in the +following sections. +

+ + + + + diff --git a/manuals/chickadee/Basics.html b/manuals/chickadee/Basics.html index 4c2d313..70d1a04 100644 --- a/manuals/chickadee/Basics.html +++ b/manuals/chickadee/Basics.html @@ -1,6 +1,6 @@ - - + Basics (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Bezier Curves (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - - - -Blending and Depth Testing (The Chickadee Game Toolkit) - - - - - - - - - - - - - - - - - - - - -
-

-Next: , Previous: , Up: Graphics   [Contents][Index]

-
-
- -

2.3.7 Blending and Depth Testing

- - - - - - diff --git a/manuals/chickadee/Blending.html b/manuals/chickadee/Blending.html index 6b3aa0d..c89f8d5 100644 --- a/manuals/chickadee/Blending.html +++ b/manuals/chickadee/Blending.html @@ -1,6 +1,6 @@ - - + Blending (The Chickadee Game Toolkit) @@ -33,28 +33,19 @@ http://www.texinfo.org/ (GNU Texinfo). - + + + + + + + +
+

+Next: , Up: Graphics   [Contents][Index]

+
+
+

2.3.1 Colors

+ +

Merriam-Webster defines color as “a phenomenon of light (such as red, +brown, pink, or gray) or visual perception that enables one to +differentiate otherwise identical objects.” In this essay, I +will… +

+

Okay, okay. We all know what colors are. Chickadee provides a data +type to represent color and some convenient procedures to work with +them in the (chickadee render color) module. Colors are made +up of four components, or channels: red, green, blue, and alpha +(transparency.) Each of these values is expressed as a uniform +floating point value in the range [0, 1]. 0 means that color channel +is unrepresented in the resulting color, whereas 1 means that color +channel is at full intensity. +

+

Making a color object is easy, and there’s a few ways to do it +depending on what’s most convenient. The first is make-color, +where you specify each channel exactly as described above. This is +fully opaque magenta: +

+
+
(make-color 1.0 0.0 1.0 1.0)
+
+ +

Many people are used to representing colors as 6 or 8 digit +hexadecimal numbers, so Chickadee also allows that. Here’s magenta, +again: +

+
+
(rgba #xFF00FFFF)
+(rgb #xFF00FF) ; equivalent to the above
+
+ +
+
Procedure: make-color r g b a
+

Return a new color object with a red value of r, a green value +of g, a blue value of b, and an alpha (transparency) value +of a. All values are clamped to the range [0, 1]. +

+ +
+
Procedure: rgba color-code
+

Return a new color object using the values of the first 32 bits of +color-code. Each channel occupies 8 bits. Starting from the +most significant bit, red is first, followed by green, then blue, then +alpha. Color codes are often represented as 6 or 8 digit hexadecimal +numbers in various other programs. +

+ +
+
Procedure: rgb color-code
+

Like rgba, but color-code is a 24 bit code with no alpha +channel. +

+ +
+
Procedure: color? obj
+

Return #t if obj is a color object. +

+ +
+
Procedure: color-r color
+

Return the red channel of color. +

+ +
+
Procedure: color-g color
+

Return the green channel of color. +

+ +
+
Procedure: color-b color
+

Return the blue channel of color. +

+ +
+
Procedure: color-a color
+

Return the alpha channel of color. +

+ +
+
Procedure: transparency alpha
+

Return a new color that is white (RGB channels set to 1) with an alpha +channel value of alpha. This can be useful for creating a color +that can be multiplied against another color to make it more +transparent. +

+ +
+
Procedure: string->color s
+

Convert the hexadecimal color code in the string s to a color +object. The following string formats are supported: +

+
+
(string->color "#FF00FFFF")
+(string->color "FF00FFFF")
+(string->color "#FF00FF")
+(string->color "FF00FF")
+
+ +
+ +
+
Procedure: color* a b
+

Multiply the color a with the color or number b and return +a new color with the result. +

+ +
+
Procedure: color+ a b
+

Add the color a to the color b and return a new color with +the result. +

+ +
+
Procedure: color- a b
+

Subtract the color b from the color a and return a new +color with the result. +

+ +
+
Procedure: color-inverse color
+

Invert the red, green, and blue channels of color and return a +new color with the result. +

+ +
+
Procedure: color-lerp start end alpha
+

Linearly interpolate the colors start and end using the +factor alpha, a number in the range [0, 1]. +

+ +

2.3.1.1 Stock Colors

+ +

For convenience, Chickadee comes with some basic colors predefined: +

+
+
Variable: white
+
+ +
+
Variable: black
+
+ +
+
Variable: red
+
+ +
+
Variable: green
+
+ +
+
Variable: blue
+
+ +
+
Variable: yellow
+
+ +
+
Variable: magenta
+
+ +
+
Variable: cyan
+
+ +

For fun, there are also predefined colors for the classic +Tango color palette. +

+
+
Variable: tango-light-butter
+
+ +
+
Variable: tango-butter
+
+ +
+
Variable: tango-dark-butter
+
+ +
+
Variable: tango-light-orange
+
+ +
+
Variable: tango-orange
+
+ +
+
Variable: tango-dark-orange
+
+ +
+
Variable: tango-light-chocolate
+
+ +
+
Variable: tango-chocolate
+
+ +
+
Variable: tango-dark-chocolate
+
+ +
+
Variable: tango-light-chameleon
+
+ +
+
Variable: tango-chameleon
+
+ +
+
Variable: tango-dark-chameleon
+
+ +
+
Variable: tango-light-sky-blue
+
+ +
+
Variable: tango-sky-blue
+
+ +
+
Variable: tango-dark-sky-blue
+
+ +
+
Variable: tango-light-plum
+
+ +
+
Variable: tango-plum
+
+ +
+
Variable: tango-dark-plum
+
+ +
+
Variable: tango-light-scarlet-red
+
+ +
+
Variable: tango-scarlet-red
+
+ +
+
Variable: tango-dark-scarlet-red
+
+ +
+
Variable: tango-aluminium-1
+
+ +
+
Variable: tango-aluminium-2
+
+ +
+
Variable: tango-aluminium-3
+
+ +
+
Variable: tango-aluminium-4
+
+ +
+
Variable: tango-aluminium-5
+
+ +
+
Variable: tango-aluminium-6
+
+ +
+
+

+Next: , Up: Graphics   [Contents][Index]

+
+ + + + + diff --git a/manuals/chickadee/Copying-This-Manual.html b/manuals/chickadee/Copying-This-Manual.html index d91e4bd..f90eeb4 100644 --- a/manuals/chickadee/Copying-This-Manual.html +++ b/manuals/chickadee/Copying-This-Manual.html @@ -1,6 +1,6 @@ - - + Copying This Manual (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Easings (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Fonts (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Framebuffers (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + GNU Free Documentation License (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Graphics (The Chickadee Game Toolkit) @@ -32,29 +32,20 @@ http://www.texinfo.org/ (GNU Texinfo). - + + + + + + + +
+

+Next: , Previous: , Up: Kernel   [Contents][Index]

+
+
+

2.1.2 Input Devices

+ +

While run-game provides hooks for mouse/keyboard/controller +input events, it is often necessary to query input devices for their +current state. For example, it could be desirable to query the state +of the arrow keys every time the update hook is called to determine +which direction the player should move that frame. +

+
+
Procedure: key-pressed? key
+

Return #t if key is currently being pressed. +

+ +
+
Procedure: key-released? key
+

Return #t if key is not currently being pressed. +

+ +
+
Procedure: mouse-x
+

Return the current X coordinate of the mouse cursor. +

+ +
+
Procedure: mouse-y
+

Return the current Y coordinate of the mouse cursor. +

+ +
+
Procedure: mouse-button-pressed? button
+

Return #t if button is currently being pressed. +

+ +
+
Procedure: mouse-button-released? button
+

Return #t if button is not currently being +pressed. +

+ +
+
Procedure: controller-axis controller axis
+

Return a floating point value in the range [-1, 1] corresponding to +how much axis (an analog stick or trigger) is being pushed on +controller. 0 is returned if axis is not being pushed at +all. +

+ +
+
Procedure: controller-name controller
+

Return the name of controller. +

+ +
+
Procedure: controller-button-pressed? controller button
+

Return #t if button on controller is currently +being pressed. +

+ +
+
Procedure: controller-button-released? controller button
+

Return #t if button on controller is not +currently being pressed. +

+ + + + + + diff --git a/manuals/chickadee/Installation.html b/manuals/chickadee/Installation.html index 11a1094..0bed587 100644 --- a/manuals/chickadee/Installation.html +++ b/manuals/chickadee/Installation.html @@ -1,6 +1,6 @@ - - + Installation (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Kernel (The Chickadee Game Toolkit) @@ -32,29 +32,20 @@ http://www.texinfo.org/ (GNU Texinfo). - + + + + + + + +
+

+Previous: , Up: Kernel   [Contents][Index]

+
+
+

2.1.4 Live Coding

+ +

One of the biggest appeals of any Lisp dialect is the ability to use +the “read-eval-print loop” (REPL for short) to build programs +iteratively and interactively while the program is running. However, +programs that run in an event loop and respond to user input (such as +a video game) require special care for this workflow to be pleasant. +Chickadee provides no built-in support for live coding, but it’s +fairly easy to hook up a special kind of REPL yourself. +

+

First, create a cooperative REPL server (It’s important to use Guile’s +cooperative REPL server instead of the standard REPL server in +(system repl server) to avoid thread synchronization issues). +Then, in the game loop’s update procedure, call +poll-coop-repl-server and pass the REPL object. Here is a +template to follow: +

+
+
(use-modules (chickadee)
+             (system repl coop-server))
+
+(define repl (spawn-coop-repl-server))
+
+(define (update dt)
+  (poll-coop-repl-server repl)
+  ...)
+
+(run-game #:update update ...)
+
+ +

To use the REPL, connect to it via port 37146. Telnet will do the +trick, but using the Geiser +extension for Emacs is by far the best way to develop at the REPL with +Guile. Use M-x connect-to-guile to connect to the REPL server. +

+ + + + + diff --git a/manuals/chickadee/Math.html b/manuals/chickadee/Math.html index fddd9cc..6636fd6 100644 --- a/manuals/chickadee/Math.html +++ b/manuals/chickadee/Math.html @@ -1,6 +1,6 @@ - - + Math (The Chickadee Game Toolkit) @@ -33,28 +33,19 @@ http://www.texinfo.org/ (GNU Texinfo). - + + + + + + + +
+

+Next: , Previous: , Up: Audio   [Contents][Index]

+
+
+

2.4.2 Sources

+ +

While the audio-play procedure provides a quick and convenient +way to play audio, it has some limitations. What if the audio is a +long piece of music that might need to be paused or stopped later? +What if the audio should be looped? What if the volume or pitch needs +to be altered? For manipulating audio in these ways, a “source” is +required. Sources can be thought of like a boombox: They sit +somewhere in the room and play sound. The pause or stop buttons can +be pressed; it can be moved somewhere else; the volume knob can be +adjusted; the CD can be changed. +

+

Sources are a great fit for handling background music, among other +things. For quick, one-off sound effects, audio-play is a +better fit. +

+
+
Procedure: make-source audio loop? [#:pitch 1.0] [#:volume 1.0] [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] [#:reference-distance 0.0] [#:rolloff-factor 1.0] [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] [#:cone-outer-angle] [#:position (vec3 0.0 0.0 0.0)] [#:velocity (vec3 0.0 0.0 0.0)] [#:direction (vec3 0.0 0.0 0.0)] [#:relative? #f]
+
+

Return a new audio source. audio is the audio data to use when +playing. loop? specifies whether or not to loop the audio +during playback. +

+

Refer to audio-play (see Audio Files) for information about +the optional keyword arguments. +

+ +
+
Procedure: source? obj
+

Return #t if obj is an audio source object. +

+ +
+
Procedure: streaming-source? source
+

Return #t if source contains streaming audio. +

+ +
+
Procedure: static-source? source
+

Return #t if source contains static audio. +

+ +
+
Procedure: source-playing? source
+

Return #t if source is currently playing. +

+ +
+
Procedure: source-paused? source
+

Return #t if source is currently paused. +

+ +
+
Procedure: source-stopped? source
+

Return #t if source is currently stopped. +

+ +
+
Procedure: source-pitch source
+

Return the pitch multiplier of source. +

+ +
+
Procedure: source-volume source
+

Return the volume multiplier of source. +

+ +
+
Procedure: source-min-volume source
+

Return the minimum volume of source. +

+ +
+
Procedure: source-max-volume source
+

Return the maximum volume of source. +

+ +
+
Procedure: source-max-distance source
+

Return the maximum distance of source. +

+ +
+
Procedure: source-reference-distance source
+

Return the reference distance of source. +

+ +
+
Procedure: source-rolloff-factor source
+

Return the rolloff factor of source. +

+ +
+
Procedure: source-cone-outer-volume source
+

Return the volume of source when outside the oriented cone. +

+ +
+
Procedure: source-cone-inner-angle source
+

Return the inner angle of the sound cone of source in radians. +

+ +
+
Procedure: source-cone-outer-angle source
+

Return the outer angle of the sound cone of source in radians. +

+ +
+
Procedure: source-position source
+

Return the position of source as a 3D vector. +

+ +
+
Procedure: source-velocity source
+

Return the velocity of source as a 3D vector. +

+ +
+
Procedure: source-direction source
+

Return the direction of source as a 3D vector. +

+ +
+
Procedure: source-relative? source
+

Return #t if the position of source is relative to the +listener’s position. +

+ +
+
Procedure: source-play source
+

Begin/resume playback of source. +

+ +
+
Procedure: source-pause source
+

Pause playback of source. +

+ +
+
Procedure: source-toggle source
+

Play source if it is currently paused or pause source if +it is currently playing. +

+ +
+
Procedure: source-stop [source]
+

Stop playing source or, if no source is specified, stop playing +all sources. +

+ +
+
Procedure: source-rewind source
+

Rewind source to the beginning of the audio stream. +

+ +
+
Procedure: set-source-audio! source audio
+

Set the playback stream for source to audio. +

+ +
+
Procedure: set-source-loop! source loop?
+

Configure whether or not source should loop the audio stream. +

+ +
+
Procedure: set-source-pitch! source pitch
+

Set the pitch multiplier of source to pitch +

+ +
+
Procedure: set-source-volume! source volume
+

Set the volume of source to volume. A value of 1.0 is +100% volume. +

+ +
+
Procedure: set-source-min-volume! source volume
+

Set the minimum volume of source to volume. +

+ +
+
Procedure: set-source-max-volume! source volume
+

Set the maximum volume of source to volume. +

+ +
+
Procedure: set-source-max-distance! source distance
+

Set the distance where there will no longer be any attenuation of +source to distance. +

+ +
+
Procedure: set-source-reference-distance! source distance
+

Set the reference distance of source to distance. +

+ +
+
Procedure: set-source-rolloff-factor! source factor
+

Set the rolloff factor for source to factor. +

+ +
+
Procedure: set-source-cone-outer-volume! source volume
+

Set the volume for source when outside the sound cone to volume. +

+ +
+
Procedure: set-source-cone-inner-angle! source angle
+

Set the inner angle of the sound cone of source to angle radians. +

+ +
+
Procedure: set-source-cone-outer-angle! source angle
+

Set the outer angle of the sound cone of source to angle radians. +

+ +
+
Procedure: set-source-position! source position
+

Set the position of source to the 3D vector position. +

+ +
+
Procedure: set-source-velocity! source velocity
+

Set the velocity of source to the 3D vector velocity. +

+ +
+
Procedure: set-source-direction! source direction
+

Set the velocity of source to the 3D vector direction. +

+ +
+
Procedure: set-source-relative! source relative?
+

If relative? is #t, the position of source is +interpreted as relative to the listener’s position. Otherwise, the +position of source is in absolute coordinates. +

+ +
+
+

+Next: , Previous: , Up: Audio   [Contents][Index]

+
+ + + + + diff --git a/manuals/chickadee/Sprites.html b/manuals/chickadee/Sprites.html index a0e308b..10a9506 100644 --- a/manuals/chickadee/Sprites.html +++ b/manuals/chickadee/Sprites.html @@ -1,6 +1,6 @@ - - + Sprites (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Textures (The Chickadee Game Toolkit) @@ -33,28 +33,19 @@ http://www.texinfo.org/ (GNU Texinfo). - + + + + + + + +
+

+Previous: , Up: Audio   [Contents][Index]

+
+
+

2.4.4 The Environment

+ +

The environment defines global parameters that govern how sound is +processed within the 3D modeling space. +

+
+
Procedure: doppler-factor
+

Return the current doppler factor. +

+ +
+
Procedure: speed-of-sound
+

Return the current speed of sound. +

+ +
+
Procedure: distance-model
+

Return the current distance model. +

+

Possible return values are: +

+
    +
  • none +
  • inverse-distance +
  • inverse-distance-clamped (the default) +
  • linear-distance +
  • linear-distance-clamped +
  • exponent-distance +
  • exponent-distance-clamped +
+ +
+ +
+
Procedure: set-doppler-factor! doppler-factor
+

Change the doppler factor to doppler-factor. +

+ +
+
Procedure: set-speed-of-sound! speed-of-sound
+

Change the speed of sound to speed-of-sound. +

+ +
+
Procedure: set-distance-model! distance-model
+

Change the distance model to distance-model. Valid distance +models are: +

+
    +
  • none +
  • inverse-distance +
  • inverse-distance-clamped +
  • linear-distance +
  • linear-distance-clamped +
  • exponent-distance +
  • exponent-distance-clamped +
+ +
+ + + + + + diff --git a/manuals/chickadee/The-Game-Loop.html b/manuals/chickadee/The-Game-Loop.html new file mode 100644 index 0000000..138dca3 --- /dev/null +++ b/manuals/chickadee/The-Game-Loop.html @@ -0,0 +1,360 @@ + + + + + + +The Game Loop (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Up: Kernel   [Contents][Index]

+
+
+

2.1.1 The Game Loop

+ +

At the very core of Chickadee there is an event loop. This loop, or +“kernel”, is responsible for ensuring that the game is updated at +the desired interval, handling input devices, rendering the current +state of the game world, and handling errors if they occur. The +kernel implements what is known as a “fixed timestep” game loop, +meaning that the game simulation will be advanced by a fixed interval +of time and will never vary from frame to frame, unlike some other +styles of game loops. The appropriately named run-game and +abort-game procedures are the entry and exit points to the +Chickadee game loop. +

+
+
Procedure: run-game [#:window-title "Chickadee!"] [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] [#:update-hz 60] [#:load] [#:update] [#:draw] [#:quit] [#:key-press] [#:key-release] [#:text-input] [#:mouse-press] [#:mouse-release] [#:mouse-move] [#:controller-add] [#:controller-remove] [#:controller-press] [#:controller-release] [#:controller-move] [#:error]
+
+

Run the Chickadee game loop. +

+

A new graphical window will be opened with window-width x +window-height as its dimensions, window-title as its +title, and in fullscreen mode if window-fullscreen? is +#t. +

+
    +
  • load: Called with zero arguments when the game window has opened +but before the game loop has started. Can be used to perform +initialization that requires an open window and OpenGL context such as +loading textures. + +
  • update: Called update-hz times per second with one +argument: The amount of time to advance the game simulation. + +
  • draw: Called each time a frame should be rendered with a single +argument known as the alpha value. See the documentation for +run-game for an explanation of this value. + +
  • quit: Called with zero arguments when the user tries to close +the game window. The default behavior is to exit the game. + +
  • key-press: Called with four arguments when a key is pressed on +the keyboard: + +
      +
    1. key: The symbolic name of the “virtual” key that was pressed. +For example: backspace. It’s called a virtual key because the +operating system may map a physical keyboard key to another key +entirely, such as how the author likes to bind the “caps lock” key +to mean “control”. + +
    2. scancode: The symbolic name of the physical key that was +pressed. + +
    3. modifiers: A list of the symbolic names of modifier keys that +were being held down when the key was pressed. Possible values +include ctrl, alt, and shift. + +
    4. repeat?: #t if this is a repeated press of the same key. + +
    + +
  • key-release: Called with three arguments when a key is released +on the keyboard: + +
      +
    1. key: The symbolic name of the “virtual” key that was released. + +
    2. scancode: The symbolic name of the physical key that was +released. + +
    3. modifiers: A list of the symbolic names of modifier keys that +were being held down when the key was released. + +
    + +
  • text-input: Called with a single argument, a string of text, +when printable text is typed on the keyboard. + +
  • mouse-press: Called with four arguments when a mouse button is +pressed: +
      +
    1. button: The symbolic name of the button that was pressed, such +as left, middle, or right. + +
    2. clicks: The number of times the button has been clicked in a row. + +
    3. x: The x coordinate of the mouse cursor. + +
    4. y: The y coordinate of the mouse cursor. + +
    + +
  • mouse-release: Called with three arguments when a mouse button +is released: + +
      +
    1. button: The symbolic name of the button that was released. + +
    2. x: The x coordinate of the mouse cursor. + +
    3. y: The y coordinate of the mouse cursor. + +
    + +
  • mouse-move: Called with five arguments when the mouse is moved: + +
      +
    1. x: The x coordinate of the mouse cursor. + +
    2. y: The y coordinate of the mouse cursor. + +
    3. dx: The amount the mouse has moved along the x axis since the +last mouse move event. + +
    4. dy: The amount the mouse has moved along the y axis since the +last mouse move event. + +
    5. buttons: A list of the buttons that were pressed down when the +mouse was moved. + +
    + +
  • controller-add: Called with a single argument, an SDL game +controller object, when a game controller is connected. + +
  • controller-remove: Called with a single argument, an SDL game +controller object, when a game controller is disconnected. + +
  • controller-press: Called with two arguments when a button on a +game controller is pressed: + +
      +
    1. controller: The controller that triggered the event. + +
    2. button: The symbolic name of the button that was pressed. +Possible buttons are: + +
        +
      • a +
      • b +
      • x +
      • y +
      • back +
      • guide +
      • start +
      • left-stick +
      • right-stick +
      • left-shoulder +
      • right-shoulder +
      • dpad-up +
      • dpad-down +
      • dpad-left +
      • dpad-right + +
      + +
    + +
  • controller-release: Called with two arguments when a button on a +game controller is released: + +
      +
    1. controller: The controller that triggered the event. + +
    2. button: The symbolic name of the button that was released. + +
    + +
  • controller-move: Called with three arguments when an analog +stick or trigger on a game controller is moved: + +
      +
    1. controller: The controller that triggered the event. + +
    2. axis: The symbolic name of the axis that was moved. Possible +values are: + +
        +
      • left-x +
      • left-y +
      • right-x +
      • right-y +
      • trigger-left +
      • trigger-right +
      + +
    + +
  • error: Called with three arguments when an error occurs: + +
      +
    1. stack: The call stack at the point of error. + +
    2. key: The exception key. + +
    3. args: The arguments thrown with the exception. + +
    + +

    The default behavior is to re-throw the error. +

    +
+ +
+ +

To stop the game loop, simply call abort-game. +

+
+
Procedure: abort-game
+

Stop the currently running Chickadee game loop. +

+ +

The above explanation of the game loop was partially a lie. It’s true +that there is a game loop at the center of Chickadee, but +run-game is not it’s true entry point. There exists an even +lower level procedure, run-game*, in the (chickadee +game-loop) module that run-game uses under the hood. +

+

On its own, run-game* does not do very much at all. In order +to actually respond to input events, update game state, or render +output, the developer must provide an engine. run-game is such +an engine, and it’s likely all a developer will need. However, what +if a developer wanted to use all of the useful Chickadee features to +make a terminal roguelike game instead? Chickadee doesn’t come with a +terminal rendering engine, but the developer could write one without +having to write their own core game loop. +

+
+
Procedure: run-game* [#:update] [#:render] [#:time] [#:error] [#:update-hz 60]
+
+

Start the game loop. This procedure will not return until +abort-game is called. +

+

The core game loop is generic and requires four additional procedures +to operate: +

+
    +
  • update: Called update-hz times per second to advance the +game simulation. This procedure is called with a single argument: The +amount of time that has passed since the last update, in milliseconds. +
  • render: Called each iteration of the loop to render the game to +the desired output device. This procedure is called with a single +argument: A value in the range [0, 1] which represents how much time +has past since the last game state update relative to the upcoming +game state update, as a percentage. Because the game state is updated +independent of rendering, it is often the case that rendering is +occuring between two updates. If the game is rendered as it was +during the last update, a strange side-effect will occur that makes +animation appear rough or “choppy”. To counter this, the +alpha value can be used to perfrom a linear interpolation of a +moving object between its current position and its previous position. +This odd trick has the pleasing result of making the animation look +smooth again, but requires keeping track of previous state. +
  • time: Called to get the current time in milliseconds. This +procedure is called with no arguments. +
  • error: Called when an error from the update or +render procedures reaches the game loop. This procedure is +called with three arguments: The call stack, the error key, and the +error arguments. If no error handler is provided, the default +behavior is to simply re-throw the error. +
+ +
+ +
+
+

+Next: , Up: Kernel   [Contents][Index]

+
+ + + + + diff --git a/manuals/chickadee/The-Listener.html b/manuals/chickadee/The-Listener.html new file mode 100644 index 0000000..b9509c9 --- /dev/null +++ b/manuals/chickadee/The-Listener.html @@ -0,0 +1,141 @@ + + + + + + +The Listener (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Audio   [Contents][Index]

+
+
+

2.4.3 The Listener

+ +

The listener is a collection of global state that represents the +player within the 3D sound model. For games that do not need 3D sound +modeling, manipulating the listener’s master volume is the only +interesting thing to do here. +

+
+
Procedure: listener-volume
+

Return the current master volume of the listener. +

+ +
+
Procedure: listener-position
+

Return the current position of the listener. +

+ +
+
Procedure: listener-velocity
+

Return the current velocity of the listener. +

+ +
+
Procedure: listener-orientation
+

Return the current orientation of the listener. +

+ +
+
Procedure: set-listener-volume! volume
+

Set the listener’s master volume to volume, a value in the range [0, +1]. +

+ +
+
Procedure: set-listener-position! position
+

Set the listener’s position to the 3D vector position. +

+ +
+
Procedure: set-listener-velocity! velocity
+

Set the listener’s velocity to the 3D vector velocity. +

+ +
+
Procedure: set-listener-orientation! at up
+

Set the listener’s orientation to the 3D vectors at and +up. +

+ + + + + + diff --git a/manuals/chickadee/Tile-Maps.html b/manuals/chickadee/Tile-Maps.html index 473d720..3990920 100644 --- a/manuals/chickadee/Tile-Maps.html +++ b/manuals/chickadee/Tile-Maps.html @@ -1,6 +1,6 @@ - - + Tile Maps (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Tweening (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - + Vectors (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). - - - -Vertex Arrays (The Chickadee Game Toolkit) - - - - - - - - - - - - - - - - - - - - -
-

-Next: , Previous: , Up: Graphics   [Contents][Index]

-
-
- -

2.3.8 Vertex Arrays

- - - - - - diff --git a/manuals/chickadee/Viewports.html b/manuals/chickadee/Viewports.html index 15b3940..0588bff 100644 --- a/manuals/chickadee/Viewports.html +++ b/manuals/chickadee/Viewports.html @@ -1,6 +1,6 @@ - - + Viewports (The Chickadee Game Toolkit) @@ -38,23 +38,14 @@ http://www.texinfo.org/ (GNU Texinfo). + + + +Window Manipulation (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Kernel   [Contents][Index]

+
+
+

2.1.3 Window Manipulation

+ +
+
Procedure: current-window
+

Return the currently active game window. +

+ +
+
Procedure: window? obj
+

Return #t if obj is a window object. +

+ +
+
Procedure: window-title window
+

Return the title of window. +

+ +
+
Procedure: window-width window
+

Return the width of window in pixels. +

+ +
+
Procedure: window-height window
+

Return the height of window in pixels. +

+ +
+
Procedure: window-x window
+

Retun the X coordinate of the upper-left corner of window. +

+ +
+
Procedure: window-y window
+

Return the Y coordinate of the upper-left corner of window. +

+ +
+
Procedure: hide-window! window
+

Hide window. +

+ +
+
Procedure: show-window! window
+

Show window. +

+ +
+
Procedure: maximize-window! window
+

Maximize window. +

+ +
+
Procedure: minimize-window! window
+

Minimize window. +

+ +
+
Procedure: raise-window! window
+

Make window visible over all other windows. +

+ +
+
Procedure: restore-window! window
+

Restore the size and position of a minimized or maximized +window. +

+ +
+
Procedure: set-window-border! window border?
+

Enable/disable the border around window. If border? is +#f, the border is disabled, otherwise it is enabled. +

+ +
+
Procedure: set-window-title! window title
+

Change the title of window to title. +

+ +
+
Procedure: set-window-size! window width height
+

Change the dimensions of window to width x height +pixels. +

+ +
+
Procedure: set-window-position! window x y
+

Move the upper-left corner of window to pixel coordinates +(x, y). +

+ +
+
Procedure: set-window-fullscreen! window fullscreen?
+

Enable or disable fullscreen mode for window. If +fullscreen? is #f, fullscreen mode is disabled, otherwise +it is enabled. +

+ + + + + + + diff --git a/manuals/chickadee/index.html b/manuals/chickadee/index.html index 4ddf0c3..1d28f4b 100644 --- a/manuals/chickadee/index.html +++ b/manuals/chickadee/index.html @@ -1,6 +1,6 @@ - - + Top (The Chickadee Game Toolkit) @@ -37,23 +37,14 @@ http://www.texinfo.org/ (GNU Texinfo).