From 24869fce4ec59701d0402e7002ab4ee94ee5c44e Mon Sep 17 00:00:00 2001 From: oakes Date: Mon, 20 Jan 2014 00:01:30 -0500 Subject: [PATCH] Add docstrings to core-graphics --- src/play_clj/core.clj | 22 +----- src/play_clj/core_global.clj | 5 +- src/play_clj/core_graphics.clj | 132 +++++++++++++++++++++++++++++++-- src/play_clj/g2d.clj | 8 +- 4 files changed, 134 insertions(+), 33 deletions(-) diff --git a/src/play_clj/core.clj b/src/play_clj/core.clj index 20dd3e5..9c65840 100644 --- a/src/play_clj/core.clj +++ b/src/play_clj/core.clj @@ -72,18 +72,7 @@ (defmacro defscreen "Creates vars for all the anonymous functions provided to it, so they can be replaced by simply reloading the namespace, and creates a var for the symbol `n` -bound to a map containing various important values related to the screen - - (defscreen main-screen - :on-show - (fn [screen entities] - (update! screen :renderer (stage)) - (label \"Hello world!\" (color :white))) - :on-render - (fn [screen entities] - (clear!) - (render! screen entities))) -" +bound to a map containing various important values related to the screen" [n & {:keys [] :as options}] `(let [fns# (->> (for [[k# v#] ~options] [k# (intern *ns* (symbol (str '~n "-" (name k#))) v#)]) @@ -100,12 +89,7 @@ bound to a map containing various important values related to the screen (defmacro defgame "Creates a var for the symbol `n` bound to a [Game](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/Game.html) -object - - (defgame hello-world - :on-create - (fn [this] - (set-screen! this main-screen)))" +object" [n & {:keys [] :as options}] `(defonce ~n (defgame* ~options))) @@ -114,7 +98,7 @@ object object, sets it as the screen for the `game`, and runs the functions from `screens` in the order they are provided in - (set-screen! hello-world main-screen) + (set-screen! hello-world main-screen text-screen) " [^Game game & screens] (let [add-inputs! (fn [] diff --git a/src/play_clj/core_global.clj b/src/play_clj/core_global.clj index 37f00ec..60f7aa0 100644 --- a/src/play_clj/core_global.clj +++ b/src/play_clj/core_global.clj @@ -17,7 +17,10 @@ (defmacro color "Returns a [Color](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/Color.html) -object" + + (color :white) + (color 1 1 1 1) +" [& args] `~(if (keyword? (first args)) `(Color. ^Color (u/static-field-upper :graphics :Color ~(first args))) diff --git a/src/play_clj/core_graphics.clj b/src/play_clj/core_graphics.clj index e5a5e54..ad6f269 100644 --- a/src/play_clj/core_graphics.clj +++ b/src/play_clj/core_graphics.clj @@ -3,21 +3,35 @@ ; tiled maps (defn tiled-map* + "The function version of `tiled-map`" [s] (if (string? s) (.load (TmxMapLoader.) s) s)) (defmacro tiled-map + "Returns a [TiledMap](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMap.html) + + (tiled-map \"level1.tmx\") +" [s & options] `(u/calls! ^TiledMap (tiled-map* ~s) ~@options)) (defmacro tiled-map! + "Calls a single method on a `tiled-map` + + (tiled-map! screen :get-layers) +" [screen k & options] `(let [^BatchTiledMapRenderer object# (u/get-obj ~screen :renderer)] (u/call! ^TiledMap (.getMap object#) ~k ~@options))) (defn tiled-map-layers + "Returns a list with [MapLayer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/MapLayer.html) +objects cooresponding to each layer in the tiled map in `screen` + + (tiled-map-layers screen) +" [screen] (let [^BatchTiledMapRenderer renderer (u/get-obj screen :renderer) ^MapLayers layers (-> renderer .getMap .getLayers)] @@ -25,6 +39,7 @@ (.get layers i)))) (defn tiled-map-layer* + "The function version of `tiled-map-layer`" [screen layer] (if (isa? (type layer) MapLayer) layer @@ -33,104 +48,161 @@ first))) (defmacro tiled-map-layer + "Returns a [TiledMapTileLayer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMapTileLayer.html) +from the tiled map in `screen` that matches `layer` + + (tiled-map-layer screen \"water\") +" [screen layer & options] `(let [^TiledMapTileLayer object# (tiled-map-layer* ~screen ~layer)] (u/calls! object# ~@options))) (defmacro tiled-map-layer! + "Calls a single method on a `tiled-map-layer` + + (tiled-map-layer! (tiled-map-layer screen \"water\") + :set-cell 0 0 nil) +" [object k & options] `(u/call! ^TiledMapTileLayer (cast TiledMapTileLayer ~object) ~k ~@options)) (defn tiled-map-cell* + "The function version of `tiled-map-cell`" [screen layer x y] (.getCell ^TiledMapTileLayer (tiled-map-layer screen layer) x y)) (defmacro tiled-map-cell + "Returns a [TiledMapTileLayer.Cell](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMapTileLayer.Cell.html) +from the tiled map in `screen` from the given `layer` and position `x` and `y` + + (tiled-map-cell screen \"water\" 0 0) +" [screen layer x y & options] `(let [^TiledMapTileLayer$Cell object# (tiled-map-cell* ~screen ~layer ~x ~y)] (u/calls! object# ~@options))) (defmacro tiled-map-cell! + "Calls a single method on a `tiled-map-cell` + + (tiled-map-cell! (tiled-map-cell screen \"water\" 0 0) + :set-rotation 90) +" [object k & options] `(u/call! ^TiledMapTileLayer$Cell ~object ~k ~@options)) ; renderers (defn orthogonal-tiled-map* + "The function version of `orthogonal-tiled-map`" [path unit] (OrthogonalTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit)) (defmacro orthogonal-tiled-map + "Returns an [OrthogonalTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/OrthogonalTiledMapRenderer.html) +with the tiled map file at `path` and `unit` scale + + (orthogonal-tiled-map \"level1.tmx\" (/ 1 8)) +" [path unit & options] `(u/calls! ^OrthogonalTiledMapRenderer (orthogonal-tiled-map* ~path ~unit) ~@options)) (defmacro orthogonal-tiled-map! + "Calls a single method on an `orthogonal-tiled-map`" [screen k & options] `(let [^OrthogonalTiledMapRenderer object# (u/get-obj ~screen :renderer)] (u/call! object# ~k ~@options))) (defn isometric-tiled-map* + "The function version of `isometric-tiled-map`" [path unit] (IsometricTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit)) (defmacro isometric-tiled-map + "Returns an [IsometricTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/IsometricTiledMapRenderer.html) +with the tiled map file at `path` and `unit` scale + + (isometric-tiled-map \"level1.tmx\" (/ 1 8)) +" [path unit & options] `(u/calls! ^IsometricTiledMapRenderer (isometric-tiled-map* ~path ~unit) ~@options)) (defmacro isometric-tiled-map! + "Calls a single method on an `isometric-tiled-map`" [screen k & options] `(let [^IsometricTiledMapRenderer object# (u/get-obj ~screen :renderer)] (u/call! object# ~k ~@options))) (defn isometric-staggered-tiled-map* + "The function version of `isometric-staggered-tiled-map`" [path unit] (IsometricStaggeredTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit)) (defmacro isometric-staggered-tiled-map + "Returns an [IsometricStaggeredTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/IsometricStaggeredTiledMapRenderer.html) +with the tiled map file at `path` and `unit` scale + + (isometric-staggered-tiled-map \"level1.tmx\" (/ 1 8)) +" [path unit & options] `(u/calls! ^IsometricStaggeredTiledMapRenderer (isometric-staggered-tiled-map* ~path ~unit) ~@options)) (defmacro isometric-staggered-tiled-map! + "Calls a single method on an `isometric-staggered-tiled-map`" [screen k & options] `(let [^IsometricStaggeredTiledMapRenderer object# (u/get-obj ~screen :renderer)] (u/call! object# ~k ~@options))) (defn hexagonal-tiled-map* + "The function version of `hexagonal-tiled-map`" [path unit] (HexagonalTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit)) (defmacro hexagonal-tiled-map + "Returns a [HexagonalTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/HexagonalTiledMapRenderer.html) +with the tiled map file at `path` and `unit` scale + + (hexagonal-tiled-map \"level1.tmx\" (/ 1 8)) +" [path unit & options] `(u/calls! ^HexagonalTiledMapRenderer (hexagonal-tiled-map* ~path ~unit) ~@options)) (defmacro hexagonal-tiled-map! + "Calls a single method on a `hexagonal-tiled-map`" [screen k & options] `(let [^HexagonalTiledMapRenderer object# (u/get-obj ~screen :renderer)] (u/call! object# ~k ~@options))) (defn stage* + "The function version of `stage`" [] (Stage.)) (defmacro stage + "Returns a [Stage](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/scenes/scene2d/Stage.html) + + (stage) +" [& options] `(u/calls! ^Stage (stage*) ~@options)) (defmacro stage! + "Calls a single method on a `stage`" [screen k & options] `(let [^Stage object# (u/get-obj ~screen :renderer)] (u/call! object# ~k ~@options))) ; batch -(defmulti batch #(-> % :renderer class)) +(defmulti batch + "Internal use only" + #(-> % :renderer class)) (defmethod batch BatchTiledMapRenderer [{:keys [^BatchTiledMapRenderer renderer]}] @@ -142,7 +214,9 @@ ; rendering -(defmulti draw-entity! (fn [_ entity] (:type entity))) +(defmulti draw-entity! + "Internal use only" + (fn [_ entity] (:type entity))) (defmethod draw-entity! nil [_ _]) @@ -167,7 +241,12 @@ height (float (or height (.getRegionHeight object)))] (.draw batch object x y width height))) -(defn draw! [{:keys [renderer] :as screen} entities] +(defn draw! + "Draws the `entities` with the renderer from `screen` + + (draw! screen entities) +" + [{:keys [renderer] :as screen} entities] (assert renderer) (let [^SpriteBatch batch (batch screen)] (.begin batch) @@ -177,11 +256,13 @@ entities) (defn ^:private render-map! + "Internal use only" [{:keys [^BatchTiledMapRenderer renderer ^Camera camera]}] (when camera (.setView renderer camera)) (.render renderer)) (defn ^:private render-stage! + "Internal use only" [{:keys [^Stage renderer ^Camera camera]}] (when camera (.setCamera renderer camera) @@ -189,6 +270,11 @@ (doto renderer .act .draw)) (defn render! + "Calls the renderer from `screen` and optionally draws and returns the +`entities` + + (render! screen entities) +" ([{:keys [renderer] :as screen}] (cond (isa? (type renderer) BatchTiledMapRenderer) @@ -202,48 +288,75 @@ ; cameras (defn orthographic* + "The function version of `orthographic`" [] (OrthographicCamera.)) (defmacro orthographic + "Returns an [OrthographicCamera](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/OrthographicCamera.html) + + (orthographic) +" [& options] `(let [^OrthographicCamera object# (orthographic*)] (u/calls! object# ~@options))) (defmacro orthographic! + "Calls a single method on an `orthographic`" [screen k & options] `(let [^OrthographicCamera object# (u/get-obj ~screen :camera)] (u/call! object# ~k ~@options))) -(defn perspective +(defn perspective* + "The function version of `perspective`" [] (PerspectiveCamera.)) (defmacro perspective + "Returns an [PerspectiveCamera](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/PerspectiveCamera.html) + + (perspective) +" [& options] `(let [^PerspectiveCamera object# (perspective*)] (u/calls! object# ~@options))) (defmacro perspective! + "Calls a single method on a `perspective`" [screen k & options] `(let [^PerspectiveCamera object# (u/get-obj ~screen :camera)] (u/call! object# ~k ~@options))) (defn size! + "Sets the size of the camera in `screen` + + (size! screen 480 360) +" [screen width height] (let [^OrthographicCamera camera (u/get-obj screen :camera)] (assert camera) (.setToOrtho camera false width height))) -(defn height! - [screen new-height] - (size! screen (* new-height (/ (game :width) (game :height))) new-height)) - (defn width! + "Sets the width of the camera in `screen`, adjusting the height so the ratio +remains in tact + + (width! screen 480) +" [screen new-width] (size! screen new-width (* new-width (/ (game :height) (game :width))))) +(defn height! + "Sets the height of the camera in `screen`, adjusting the width so the ratio +remains in tact + + (height! screen 360) +" + [screen new-height] + (size! screen (* new-height (/ (game :width) (game :height))) new-height)) + (defn x! + "Sets only the x position of the camera in `screen`" [screen x] (let [^Camera camera (u/get-obj screen :camera)] (assert camera) @@ -251,6 +364,7 @@ (.update camera))) (defn y! + "Sets only the y position of the camera in `screen`" [screen y] (let [^Camera camera (u/get-obj screen :camera)] (assert camera) @@ -258,6 +372,7 @@ (.update camera))) (defn z! + "Sets only the z position of the camera in `screen`" [screen z] (let [^Camera camera (u/get-obj screen :camera)] (assert camera) @@ -265,6 +380,7 @@ (.update camera))) (defn position! + "Sets the position of the camera in `screen`" ([screen x y] (position! screen x y nil)) ([screen x y z] diff --git a/src/play_clj/g2d.clj b/src/play_clj/g2d.clj index 7db1526..8fbacbb 100644 --- a/src/play_clj/g2d.clj +++ b/src/play_clj/g2d.clj @@ -39,8 +39,7 @@ entity#)) (defmacro texture! - "Calls a single method on a `texture` entity, returning whatever the method -itself does + "Calls a single method on a `texture` (texture! entity :flip true false) (texture! entity :get-region-width) @@ -69,7 +68,7 @@ itself does (play-mode :normal))) (defmacro animation - "Returns an [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html) object + "Returns an [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html) (animation 0.2 [walk-1 walk-2 walk-3] @@ -79,8 +78,7 @@ itself does `(u/calls! ^Animation (animation* ~duration ~textures) ~@options)) (defmacro animation! - "Calls a single method on an `animation` object, returning whatever the method -itself does + "Calls a single method on an `animation` (animation! object :set-play-mode (play-mode :loop)) "