extra/game/loop/loop-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: help.markup help.syntax kernel math ui.gadgets.worlds ;
   3 IN: game.loop
   4
   5 HELP: fps
   6 { $values { "fps" real } { "micros" integer } }
   7 { $description "Converts a frames per second value into an interval length in microseconds." } ;
   8
   9 HELP: <game-loop>
  10 { $values
  11     { "tick-interval-micros" integer } { "delegate" "a " { $link "game.loop-delegates" } }
  12     { "loop" game-loop }
  13 }
  14 { $description "Constructs a new stopped " { $link game-loop } " object. When started, the game loop will call the " { $link tick* } " method on the " { $snippet "delegate" } " every " { $snippet "tick-interval-micros" } " microseconds, and " { $link draw* } " on the same delegate object as frequently as possible. The " { $link start-loop } " and " { $link stop-loop } " words start and stop the game loop."
  15 $nl
  16 "To initialize the game loop with separate tick and draw delegates, use " { $link <game-loop*> } "." } ;
  17
  18 HELP: <game-loop*>
  19 { $values
  20     { "tick-interval-micros" integer } { "tick-delegate" "a " { $link "game.loop-delegates" } } { "draw-delegate" "a " { $link "game.loop-delegates" } }
  21     { "loop" game-loop }
  22 }
  23 { $description "Constructs a new stopped " { $link game-loop } " object. When started, the game loop will call the " { $link tick* } " method on the " { $snippet "tick-delegate" } " every " { $snippet "tick-interval-micros" } " microseconds, and " { $link draw* } " on the " { $snippet "draw-delegate" } " as frequently as possible. The " { $link start-loop } " and " { $link stop-loop } " words start and stop the game loop."
  24 $nl
  25 "The " { $link <game-loop> } " word provides a shorthand for initializing a game loop that uses the same object for the " { $snippet "tick-delegate" } " and " { $snippet "draw-delegate" } "." } ;
  26
  27 { <game-loop> <game-loop*> } related-words
  28
  29 HELP: benchmark-frames-per-second
  30 { $values
  31     { "loop" game-loop }
  32     { "n" float }
  33 }
  34 { $description "Returns the average number of times per second the game loop has called " { $link draw* } " on its delegate since the game loop was started with " { $link start-loop } " or since the benchmark counters have been reset with " { $link reset-loop-benchmark } "." } ;
  35
  36 HELP: benchmark-ticks-per-second
  37 { $values
  38     { "loop" game-loop }
  39     { "n" float }
  40 }
  41 { $description "Returns the average number of times per second the game loop has called " { $link tick* } " on its tick delegate since the game loop was started with " { $link start-loop } " or since the benchmark counters have been reset with " { $link reset-loop-benchmark } "." } ;
  42
  43 { reset-loop-benchmark benchmark-frames-per-second benchmark-ticks-per-second } related-words
  44
  45 HELP: draw*
  46 { $values
  47     { "tick-slice" float } { "delegate" "a " { $link "game.loop-delegates" } }
  48 }
  49 { $description "This generic word is called by a " { $link game-loop } " on its " { $snippet "draw-delegate" } " object in a tight loop while the game loop is running. The " { $snippet "tick-slice" } " value represents what fraction of the game loop's " { $snippet "tick-interval-micros" } " time period has passed since " { $link tick* } " was most recently called on the " { $snippet "tick-delegate" } "." } ;
  50
  51 HELP: game-loop
  52 { $class-description "Objects of the " { $snippet "game-loop" } " class manage game loops. See " { $link "game.loop" } " for an overview of the game loop library. To construct a game loop, use " { $link <game-loop> } ". To start and stop a game loop, use the " { $link start-loop } " and " { $link stop-loop } " words."
  53 $nl
  54 "The " { $snippet "tick-delegate" } " and " { $snippet "draw-delegate" } " slots of a game loop object determine where the loop sends its " { $link tick* } " and " { $link draw* } " events. These slots can be changed while the game loop is running." } ;
  55
  56 HELP: game-loop-error
  57 { $values
  58     { "game-loop" game-loop } { "error" "an error object" }
  59 }
  60 { $description "If an uncaught error is thrown from inside a game loop delegate's " { $link tick* } " or " { $link draw* } ", the game loop will catch the error, stop the game loop, and rethrow an error of this class." } ;
  61
  62 HELP: reset-loop-benchmark
  63 { $values
  64     { "loop" game-loop }
  65 }
  66 { $description "Resets the benchmark counters on a " { $link game-loop } ". Subsequent calls to " { $link benchmark-frames-per-second } " and " { $link benchmark-ticks-per-second } " will measure their values from the point " { $snippet "reset-loop-benchmark" } " was called." } ;
  67
  68 HELP: start-loop
  69 { $values
  70     { "loop" game-loop }
  71 }
  72 { $description "Starts running a " { $link game-loop } "." } ;
  73
  74 HELP: stop-loop
  75 { $values
  76     { "loop" game-loop }
  77 }
  78 { $description "Stops running a " { $link game-loop } "." } ;
  79
  80 { start-loop stop-loop } related-words
  81
  82 HELP: tick*
  83 { $values
  84     { "delegate" "a " { $link "game.loop-delegates" } }
  85 }
  86 { $description "This generic word is called by a " { $link game-loop } " on its " { $snippet "tick-delegate" } " object at regular intervals while the game loop is running. The game loop's " { $snippet "tick-interval-micros" } " attribute determines the number of microseconds between invocations of " { $snippet "tick*" } "." } ;
  87
  88 { draw* tick* } related-words
  89
  90 ARTICLE: "game.loop-delegates" "Game loop delegate"
  91 "A " { $link game-loop } " object requires a " { $snippet "tick-delegate" } " and " { $snippet "draw-delegate" } " that together implement the logic that controls the game. Both delegates can also be the same object. A game loop delegate can be any object that provides two methods for the following generic words:"
  92 { $subsections
  93     tick*
  94     draw*
  95 }
  96 { $snippet "tick*" } " will be called at a regular interval determined by the game loop's " { $snippet "tick-interval-micros" } " attribute on the tick delegate. " { $snippet "draw*" } " will be invoked on the draw delegate in a tight loop, updating as frequently as possible."
  97 $nl
  98 "It is possible to change the " { $snippet "tick-delegate" } " and " { $snippet "draw-delegate" } " slots of a game loop while it is running, for example, to use different delegates to control a game while it's in the menu, paused, or running the main game." ;
  99
 100 ARTICLE: "game.loop" "Game loops"
 101 "The " { $vocab-link "game.loop" } " vocabulary contains the implementation of a game loop. The game loop supports decoupled rendering and game logic timers; given a \"tick delegate\" object with a method on the " { $link tick* } " generic and a \"draw delegate\" with a " { $link draw* } " method, the game loop will invoke the " { $snippet "tick*" } " method on the former at regular intervals while invoking the " { $snippet "draw*" } " method on the latter as frequently as possible. Game loop objects must first be constructed:"
 102 { $subsections
 103     "game.loop-delegates"
 104     <game-loop>
 105     <game-loop*>
 106 }
 107 "Once constructed, the game loop can be started and stopped:"
 108 { $subsections
 109     start-loop
 110     stop-loop
 111 }
 112 "The game loop maintains performance counters for measuring drawing frames and ticks per second:"
 113 { $subsections
 114     reset-loop-benchmark
 115     benchmark-frames-per-second
 116     benchmark-ticks-per-second
 117 }
 118 "The game loop manages errors that occur in the delegate's methods during the course of the game loop:"
 119 { $subsections
 120     game-loop-error
 121 }
 122 "The " { $vocab-link "game.worlds" } " vocabulary provides a convenient " { $link world } " subclass that integrates the game loop implementation with UI applications, managing the starting and stopping of the loop for you." ;
 123
 124 ABOUT: "game.loop"