More documentation, added some additional dependencies for future expansion of the library (SDL_ffmpeg, yaml-cpp)

Makefile

@@ -81,7 +81,7 @@ staticlib: $(LIBOBJ)
 
 .PHONY: docs
 docs:
-	doxygen doxygen.conf
+	cd libsdlgame && doxygen doxygen.conf
 
 .PHONY: clean
 clean:

deps/Makefile

@@ -3,15 +3,11 @@ all: clean packages
 CFLAGS=$(CFLAGS) -I/usr/local/include -I/usr/include
 LDFLAGS=$(LDFLAGS) -L/usr/local/lib -L/usr/lib
 
-.PHONY: files
-files:
-	wget http://downloads.xiph.org/releases/theora/libtheora-1.1.1.tar.bz2
-
 .PHONY: packages
-packages: SDL_main zlib libpng libjpeg libtiff SDL_image libvorbis flac SDL_mixer freetype SDL_ttf SDL_gfx libxml2
+packages: SDL zlib libpng libjpeg libtiff SDL_image libvorbis flac SDL_mixer freetype SDL_ttf SDL_gfx libxml2 cmake ffmpeg SDL_ffmpeg
 
-.PHONY: SDL_main
+.PHONY: SDL
-SDL_main:
+SDL:
 	wget http://www.libsdl.org/release/SDL-1.2.14.tar.gz
 	tar -zxvf SDL-1.2.14.tar.gz
 	cd SDL-1.2.14 && ./configure  && make && make install
@@ -117,6 +113,37 @@ doxygen:
 	wget http://ftp.stack.nl/pub/users/dimitri/doxygen-1.7.4.windows.bin.zip
 	unzip -od /bin doxygen-1.7.4.windows.bin.zip
 
+# Just for the record - cmake is fuckin bullshit.
+.PHONY: cmake
+cmake:
+	wget http://www.cmake.org/files/v2.8/cmake-2.8.4-win32-x86.zip
+	unzip cmake-2.8.4-win32-x86.zip
+	cp -vR cmake-2.8.4-win32-x86/* /usr/local/
+#wget http://www.cmake.org/files/v2.8/cmake-2.8.4.tar.gz
+#cd cmake-2.8.4 && ./configure && make && make install
+
+.PHONY: ffmpeg
+ffmpeg:
+	wget http://www.ffmpeg.org/releases/ffmpeg-0.7-rc1.tar.gz
+	tar -zxvf ffmpeg-0.6.3.tar.gz
+	cd ffmpeg-0.6.3 && ./configure $(FFMPEG_CONFIGURE_FLAGS) && make && make install
+
+.PHONY: SDL_ffmpeg
+SDL_ffmpeg:
+	wget http://www.arjanhouben.nl/SDL_ffmpeg/1.3.1/SDL_ffmpeg-1.3.1.tar.gz
+	tar -zxvf SDL_ffmpeg-1.3.1.tar.gz
+	cd SDL_ffmpeg && cmake -G "MSYS Makefiles" . && make
+	cp SDL_ffmpeg/lib/libSDL_ffmpeg.dll.a /usr/local/lib/
+	cp SDL_ffmpeg/include/SDL/SDL_ffmpeg.h /usr/local/include
+
+.PHONY: yaml-cpp
+yaml-cpp:
+	wget http://yaml-cpp.googlecode.com/files/yaml-cpp-0.2.6.tar.gz
+	tar -zxvf yaml-cpp-0.2.6.tar.gz
+	cd yaml-cpp && cmake -G "MSYS Makefiles" . && make
+	cp -vR yaml-cpp/include/yaml-cpp /usr/local/include/
+	cp yaml-cpp/libyaml-cpp.a /usr/local/lib/
+
 .PHONY: clean
 clean:	
 	rm -rf *gz *zip *bz2

libsdlgame/Actor.h

@@ -6,56 +6,62 @@
 #include "Renderable.h"
 #include "Animation.h"
 
-#define STATE_NONE		0
-#define STATE_DYING		2
-#define STATE_DEAD		4
-#define STATE_MOVEXAXIS		(8 | 16) 
-#define STATE_MOVELEFT		8
-#define STATE_MOVERIGHT		16
-#define STATE_MOVEYAXIS		(32 | 64)
-#define STATE_MOVEUP		32
-#define STATE_MOVEDOWN		64
-#define STATE_VISIBLE		128
-#define STATE_INVINCIBLE	256
-#define STATE_SPAWNWAIT		512
-#define STATE_FADEIN		1024
-#define STATE_FADEOUT		2048
-#define STATE_ATTACKING		4096
-#define STATE_MOVEIN		8192
-#define STATE_MOVEOUT		16384
-#define STATE_RENDERPARENT	32768 	// this status flag specifies that, when an Actor has a Parent,
-					// the position returned by this actor should be relative to their parent
 
-#define STATE_DEFAULT		0xFFFFFFFF
+#define STATE_NONE		0 /**< No state */
+#define STATE_DYING		2 /**< Dying */
+#define STATE_DEAD		4 /**< Dead */
+#define STATE_MOVEXAXIS		(8 | 16) /**< Moving on X axis */
+#define STATE_MOVELEFT		8 /**< Moving to the left */
+#define STATE_MOVERIGHT		16 /**< moving to the right */
+#define STATE_MOVEYAXIS		(32 | 64) /** Moving on the Y axis */
+#define STATE_MOVEUP		32 /**< Moving up */
+#define STATE_MOVEDOWN		64 /**< Moving down */
+#define STATE_VISIBLE		128 /**< Visible */
+#define STATE_INVINCIBLE	256 /**< Invincible */
+#define STATE_SPAWNWAIT		512 /**< Waiting for respawn */
+#define STATE_FADEIN		1024 /**< Fading in */
+#define STATE_FADEOUT		2048 /**< Fading out */
+#define STATE_ATTACKING		4096 /**< Attacking */
+#define STATE_MOVEIN		8192 /**< I don't know */
+#define STATE_MOVEOUT		16384 /**< I don't know */
+#define STATE_RENDERPARENT	32768 /**< When an Actor has a Parent, the position returned by this actor should be relative to their parent */
+
+#define STATE_DEFAULT		0xFFFFFFFF /**< Default state is ZOMGEVERYFUCKINTHING */
+
+/**
+ * @class Actor
+ * @brief A class that represents an on-screen object that moves, has logic, etc
+ */
 
 class Actor : public AnimatedRenderable
 {
 protected:
-    int state;
+  int state; /**< A bitmask of the various STATE_* defines to define actor's current state */
-    FrameCounter logicCounter;
+  FrameCounter logicCounter; /**< A FrameCounter used to track logic timing */
-    unsigned int userType;
+  unsigned int userType; /**< A custom integer value that can be set by users to define custom types to track */
 public:
-    AnimationStateMap *animMap;
+  AnimationStateMap *animMap; /**< Map of Animation objects keyed by state value */
-    Actor(AnimationStateMap *animMap, Vector position, Vector velocity);
+  Actor(AnimationStateMap *animMap, Vector position, Vector velocity);
-    Actor();
+  Actor();
-    virtual ~Actor();
+  virtual ~Actor();
-    virtual SDL_Surface *nextFrame();
+  virtual SDL_Surface *nextFrame();
-    virtual Vector getPosition(char gfxanchor = 0);
+  virtual Vector getPosition(char gfxanchor = 0);
-    virtual int addAnimation(Animation *anim, unsigned int key);
+  virtual int addAnimation(Animation *anim, unsigned int key);
-    virtual Animation *getAnimation(unsigned int stateKey);
+  virtual Animation *getAnimation(unsigned int stateKey);
-    virtual void setState(int state);
+  virtual void setState(int state);
-    virtual int getState();
+  virtual int getState();
-    virtual void addState(int state);
+  virtual void addState(int state);
-    virtual void removeState(int state);
+  virtual void removeState(int state);
-    virtual int hasState(int state);
+  virtual int hasState(int state);
-    virtual void update();
+  virtual void update();
-    virtual void collide(Actor *ptr) {};
+  virtual void collide(Actor *ptr) {};
-    virtual unsigned int getUserType();
+  virtual unsigned int getUserType();
-    virtual void setUserType(unsigned int type);
+  virtual void setUserType(unsigned int type);
-
+  
-    Actor *parent;
+  Actor *parent; /**< Can be used to specify a parent Actor, relative to whom this Actor will be rendered. */
 };
 
+
 typedef std::vector<Actor *> ActorList;
 typedef std::vector<Actor *>::iterator ActorListIterator;
 

libsdlgame/Animation.cpp

@@ -4,12 +4,12 @@
 #include "Actor.h"
 #include <iostream>
 
-// TODO: Animation has mysterious segfault problems when it is used static; e.g.
+/** TODO: Animation has mysterious segfault problems when it is used static; e.g.
-//
+ *
-//	Animation anim; <-- using this object will eventually cause a segfault thru the framecounters/indexers
+ *	Animation anim; <-- using this object will eventually cause a segfault thru the framecounters/indexers
-//	..
+ *	..
-//	Animation *anim = new Animation() <-- ... using this one will not
+ *	Animation *anim = new Animation() <-- ... using this one will not
-
+ */
 Animation::Animation()
 {
     this->strip = NULL;
@@ -23,6 +23,15 @@ Animation::~Animation()
 {
 }
 
+/**
+ * @brief Sets the sprite strip used by this animation
+ * @param strip sprite strip from which animation frames should be pulled
+ * @param fps lock the animation speed to a given frames per second
+ * @param loop 0 = play once and stop, 1 = loop continually
+ * @param anchor The actual position of this animation in relation to the actor using it
+ *
+ * Doxygen doesn't show the fourth parameter to this function for some reason. it is (Vector anchor) and defaults to {0,0,0}
+ */
 int Animation::setStrip(SpriteStrip *strip, int fps, int loop, Vector anchor)
 {
     if ( strip == NULL ) {
@@ -42,9 +51,22 @@ int Animation::setStrip(SpriteStrip *strip, int fps, int loop, Vector anchor)
     return 0;
 }
 
-// FIXME : The way this interaction works is INCREDIBLY hackish. I should look
+/**
-// at collapsing the nextFrame() functionality into Actor, and basically redoing the
+ * @brief Return the next frame of this animation to be rendered
-// Animation class as a structure that does nothing. For now, though, this works.
+ * @param curFrame Frame to render, or 0 if actorSource is set
+ * @param lastTime Last update time, or 0 if actorSource is set
+ * @param actorSource The actor for which this animation is being rendered, or NULL
+ * 
+ * Performs logic necessary to check time from lastTime vs current time to return the
+ * appropriate frame. If actorSource is set, it will pull a FrameCounter from that actor
+ * to use for curFrame/lastTime.
+ *
+ * FIXME : The way this interaction works is INCREDIBLY hackish. I should look
+ * at collapsing the nextFrame() functionality into Actor, and basically redoing the
+ * Animation class as a structure that does nothing. For now, though, this works.
+ *
+ * @return (SDL_Surface *) Will return the first frame of animation if the animation is stopped, otherwise will return the current frame. Will only return NULL if the Animation has no frames assigned.
+ */
 
 SDL_Surface *Animation::nextFrame(int curFrame, int lastTime, AnimatedRenderable *actorSource)
 {
@@ -90,6 +112,11 @@ SDL_Surface *Animation::nextFrame(int curFrame, int lastTime, AnimatedRenderable
 	return toRet;
 }
 
+/**
+ * @brief return the number of frames in this animation
+ * @return integer
+ */
+
 int Animation::numFrames()
 {
     if ( this->strip != NULL ) { 
@@ -98,6 +125,10 @@ int Animation::numFrames()
     return 0;
 }
 
+/**
+ * @brief Return a new vector modified by the anchor vector
+ * @return a new vector
+ */
 Vector Animation::anchorAt(Vector position)
 {
     Vector newVector;

libsdlgame/Animation.h

@@ -6,28 +6,34 @@
 #include "Renderable.h"
 #include <map>
 
+/**
+ * @class Animation
+ * @brief A class for handling animation states related to sprite strips
+ */
+
 class Animation
 {
-private:
+ protected:
-    unsigned int lastTime;
+  unsigned int lastTime; /**< the time of the last animation update */
-    SpriteStrip *strip;
+  SpriteStrip *strip; /**< The spritestrip used by this animation */
-    unsigned int timeStep;
+  unsigned int timeStep; /**< The number of ticks between each frame */
-    int fps;
+  int fps; /**< locked frames per second */
-    int loop;
+  int loop; /**< 1 = loop continually, 0 = play once and stop */
-    Vector anchor; 
+  Vector anchor; /**< Position relative to (0, 0) which is the actual anchor point for this animation */
-public:
+ public:
-    Animation();
+  Animation();
-    virtual ~Animation();
+  virtual ~Animation();
-    int getLoop() { return this->loop; };
+  /** @brief Returns the value of 'loop' */
-    int setStrip(SpriteStrip *strip, int fps, int loop = 0, Vector anchor = (Vector){0,0,0});
+  int getLoop() { return this->loop; };
-    SDL_Surface *nextFrame(int curFrame, int lastTime, AnimatedRenderable *actorSource = NULL);
+  int setStrip(SpriteStrip *strip, int fps, int loop = 0, Vector anchor = (Vector){0,0,0});
-    int numFrames();
+  SDL_Surface *nextFrame(int curFrame, int lastTime, AnimatedRenderable *actorSource = NULL);
-    Vector anchorAt(Vector position);
+  int numFrames();
+  Vector anchorAt(Vector position);
 };
 
-//typedef std::map<std::string, Animation *> AnimationMap;
+/** A hashmap to tie animation states (integer bitflags) to animation pointers */
-//typedef std::map<std::string, Animation *>::iterator AnimationMapIterator;
 typedef std::map<unsigned int, Animation *> AnimationStateMap;
+/** An iterator for AnimationStateMap */
 typedef std::map<unsigned int, Animation *>::iterator AnimationStateMapIterator;
 
 

libsdlgame/Common.h

@@ -3,8 +3,16 @@
 
 #include <SDL.h>
 
+/**
+ * @def GAMEFPS
+ * Redefine this value to change the FPS you want the game to lock to (USUALLY works)
+*/
 #define GAMEFPS		60
 
+/**
+ * @struct Vector
+ * @brief A simple way of representing a 3-dimensional point or vector
+ */
 struct Vector
 {
     float x;
@@ -12,13 +20,21 @@ struct Vector
     float z;
 };
 
+/**
+ * @typedef Point
+ * @brief A convenient typedef for Vector
+ */
 typedef Vector Point;
 
+/**
+ * @struct FrameCounter
+ * @brief A structure to use for counting frame times and positions
+ */
 struct FrameCounter
 {
-    unsigned int curFrame;
+  unsigned int curFrame; /**< current frame */
-    unsigned int lastTime;
+  unsigned int lastTime; /**< ticks at last logic */
-    SDL_Surface *lastFrame;
+  SDL_Surface *lastFrame; /**< previous frame returned by this counter */
 };
 
 /**
@@ -32,7 +48,7 @@ struct FrameCounter
 class SharedCanvas2D
 {
 protected:
-    SDL_Surface *canvas;
+  SDL_Surface *canvas; /**< actual SDL_Surface used by this SharedCanvas */
 public:
     SharedCanvas2D();
     virtual ~SharedCanvas2D();

libsdlgame/Display.cpp

@@ -15,16 +15,36 @@ Display::~Display()
     }
 }
 
+/**
+ * @return integer, 0 for inactive, 1 for active
+ * @brief return the active state of this display
+ */
+
 int Display::isActive()
 {
     return this->active;
 }
 
+/**
+ * @param active integer, 0 or 1
+ * @brief Toggle the active flag on this display
+ */
+
 void Display::setActive(int active)
 {
     this->active = active;
 }
 
+/**
+ * @param pos Vector, position of this window relative to any parents
+ * @param w integer, width of the canvas
+ * @param h integer, height of the canvas
+ * @param depth integer, bit depth of the canvas
+ * @param flags integer, flags passed to SDL_CreateRGBSurface
+ * @brief Setup the rendering surface this display will use
+ * @return 0 on success, 1 on failure
+ */
+
 int Display::initVideo(Vector pos, int w, int h, int depth, int flags)
 {
 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
@@ -48,6 +68,14 @@ int Display::initVideo(Vector pos, int w, int h, int depth, int flags)
     return 0;
 }
 
+/**
+ * @param actor Actor *, the actor to add to the actor list
+ * @brief Add 'actor' to this display
+ * @return 0 on success, 1 on failure
+ *
+ * Adds an actor to this display's actor list to be managed on the canvas. 
+ * Actors are pushed to the back end of the list by default.
+ */
 int Display::addActor(Actor *actor)
 {
      if ( actor == NULL ) {
@@ -67,6 +95,12 @@ int Display::addActor(Actor *actor)
      return 0;
 }
 
+/**
+ * @param index unsigned integer
+ * @brief return the actor at index 'index' of this display's actor list
+ * @return (Actor *), actor if present in the list, or NULL otherwise
+ */
+
 Actor *Display::getActor(unsigned int index)
 {
     if ( index < this->actors.size() ) {
@@ -75,6 +109,11 @@ Actor *Display::getActor(unsigned int index)
     return NULL;
 }
 
+/**
+ * @param actor (Actor *), actor to remove from this display
+ * @return 0 on success, 1 on failure
+ * @brief Remove a given actor from this display's actor list
+ */
 int Display::removeActor(Actor *actor)
 {
     ActorListIterator iter = this->actors.begin();
@@ -100,11 +139,19 @@ SDL_Surface *Display::nextFrame()
     }
 }
 
+/**
+ * @return SDL_PixelFormat
+ * @brief return the pixel format of the current canvas
+ */
 SDL_PixelFormat *Display::pixelFormat()
 {
     return this->canvas->format;
 }
 
+/**
+ * @param userType (unsigned int) the user type to check for
+ * @brief Returns a count of all objects in this display's actor list that match the given user defined type
+ */ 
 int Display::objectsOfType(unsigned int userType)
 {
     int ocount = 0;

libsdlgame/Display.h

@@ -6,24 +6,34 @@
 #include "FontRenderer.h"
 #include <SDL.h>
 
+/** 
+ * @class Display
+ * @brief A class for managing a scene
+ *
+ * This class provides a method of managing scenes. It gives access
+ * to a rendering port through Renderable/SharedCanvas2D; it provides
+ * management of on-screen actors, and provides a basic logic update
+ * framework.
+ */
+
 class Display : public Renderable, public SharedCanvas2D
 {
 protected:
-    ActorList actors;
+  ActorList actors; /**< list of actors currently assigned to this display */
-    int active;
+  int active; /**< boolean flag, 0 for inactive, 1 for active. This controls visibility and logic. */
 public:
-    Display();
+  Display();
-    virtual ~Display();
+  virtual ~Display();
-    virtual int isActive();
+  virtual int isActive();
-    virtual void setActive(int active);
+  virtual void setActive(int active);
-    virtual int initVideo(Vector pos, int w, int h, int depth, int flags);
+  virtual int initVideo(Vector pos, int w, int h, int depth, int flags);
-    virtual SDL_Surface *nextFrame();
+  virtual SDL_Surface *nextFrame();
-    virtual int addActor(Actor *actor = NULL);
+  virtual int addActor(Actor *actor = NULL);
-    virtual Actor *getActor(unsigned int index);
+  virtual Actor *getActor(unsigned int index);
-    virtual int removeActor(Actor *actor);
+  virtual int removeActor(Actor *actor);
-    virtual void update(int logicOnly = 0) {};
+  virtual void update(int logicOnly = 0) {};
-    SDL_PixelFormat *pixelFormat();
+  SDL_PixelFormat *pixelFormat();
-    virtual int objectsOfType(unsigned int userType);
+  virtual int objectsOfType(unsigned int userType);
 };
 
 #endif // __DISPLAY_H__