Merge pull request #247 from blackberry-gaming/next-dgough

Next dgough

gameplay-encoder/src/DAESceneEncoder.h

@@ -185,7 +185,8 @@ private:
      * Returns the VertexUsage value for the given semantic string.
      * 
      * @param semantic The semantic attribute string from the COLLADA <input> element.
-     * @param The VertexUsage or -1 if the string was not recognized.
+     * 
+     * @return The VertexUsage or -1 if the string was not recognized.
      */
     static int getVertexUsageType(const std::string& semantic);
     

gameplay/src/AnimationTarget.h

@@ -28,7 +28,6 @@ public:
      * Cannot use Curve::BEZIER or CURVE::HERMITE as the interpolation type since they require tangents/control points.
      * 
      * @param id The ID of the animation.
-     * @param target The animation target.
      * @param propertyId The property on this target to animate.
      * @param keyCount The number of keyframes in the animation. Must be greater than one.
      * @param keyTimes The list of key times for the animation (in milliseconds).
@@ -43,7 +42,6 @@ public:
      * Creates an animation on this target from a set of key value and key time pairs.
      * 
      * @param id The ID of the animation.
-     * @param target The animation target.
      * @param propertyId The property on this target to animate.
      * @param keyCount The number of keyframes in the animation. Must be greater than one.
      * @param keyTimes The list of key times for the animation (in milliseconds).
@@ -60,7 +58,6 @@ public:
      * Creates an animation on this target using the data from the given properties object. 
      * 
      * @param id The ID of the animation.
-     * @param target The animation target.
      * @param animationFile The animation file defining the animation data.
      *
      * @return The newly created animation.
@@ -71,8 +68,7 @@ public:
      * Creates an animation on this target using the data from the given properties object. 
      * 
      * @param id The ID of the animation.
-     * @param target The animation target.
-     * @param properties The properties object defining the animation data.
+     * @param animationProperties The properties object defining the animation data.
      *
      * @return The newly created animation.
      */
@@ -83,7 +79,6 @@ public:
      * Cannot use Curve::BEZIER or CURVE::HERMITE as the interpolation type since they require tangents/control points.
      *
      * @param id The ID of the animation.
-     * @param target The animation target.
      * @param propertyId The property on this target to animate.
      * @param from The values to animate from.
      * @param to The values to animate to.
@@ -99,7 +94,6 @@ public:
      * Cannot use Curve::BEZIER or CURVE::HERMITE as the interpolation type since they require tangents/control points.
      *
      * @param id The ID of the animation.
-     * @param target The animation target.
      * @param propertyId The property on this target to animate.
      * @param from The values to animate from.
      * @param by The values to animate by.
@@ -113,7 +107,7 @@ public:
     /**
      * Destroys the animation with the specified ID. Destroys the first animation if ID is NULL.
      *
-     * @param The animation to destroy.
+     * @param id The ID of the animation to destroy.
      */ 
     void destroyAnimation(const char* id = NULL);
 

gameplay/src/CheckBox.h

@@ -112,7 +112,7 @@ protected:
      * Draw the checkbox icon associated with this control.
      *
      * @param spriteBatch The sprite batch containing this control's icons.
-     * @param position The container position this control is relative to.
+     * @param clip The container position this control is relative to.
      */
     void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 

gameplay/src/Container.h

@@ -73,7 +73,7 @@ public:
     /**
      * Remove a control with the given ID.
      *
-     * @param ID The ID of the control to remove.
+     * @param id The ID of the control to remove.
      */
     void removeControl(const char* id);
 

gameplay/src/Control.h

@@ -213,6 +213,8 @@ public:
      * @param bottom The height of the border's bottom side.
      * @param left The width of the border's left side.
      * @param right The width of the border's right side.
+     * @param states The states to set this property on.
+     *               One or more members of the Control::State enum, ORed together.
      */
     void setBorder(float top, float bottom, float left, float right, unsigned char states = STATE_ALL);
 
@@ -356,6 +358,7 @@ public:
     /**
      * Set the texture region of this control's cursor.
      *
+     * @param region The cursor region.
      * @param states The states to set this property on.
      *               One or more members of the Control::State enum, ORed together.
      */

gameplay/src/Font.cpp

@@ -689,7 +689,7 @@ void Font::measureText(const char* text, unsigned int size, unsigned int* width,
     }
 }
 
-void Font::measureText(const char* text, const Rectangle& viewport, unsigned int size, Rectangle* out, Justify justify, bool wrap, bool ignoreClip)
+void Font::measureText(const char* text, const Rectangle& clip, unsigned int size, Rectangle* out, Justify justify, bool wrap, bool ignoreClip)
 {
     float scale = (float)size / _size;
     Justify vAlign = static_cast<Justify>(justify & 0xF0);
@@ -709,8 +709,8 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
     std::vector<Vector2> lines;
 
     unsigned int lineWidth = 0;
-    int yPos = viewport.y;
-    const float viewportHeight = viewport.height - size;
+    int yPos = clip.y;
+    const float viewportHeight = clip.height - size;
 
     if (wrap)
     {
@@ -739,8 +739,8 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
                         if (lineWidth > 0)
                         {
                             // Determine horizontal position and width.
-                            int hWhitespace = viewport.width - lineWidth;
-                            int xPos = viewport.x;
+                            int hWhitespace = clip.width - lineWidth;
+                            int xPos = clip.x;
                             if (hAlign == ALIGN_HCENTER)
                             {
                                 xPos += hWhitespace / 2;
@@ -791,14 +791,14 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
             unsigned int tokenWidth = getTokenWidth(token, tokenLength, size, scale);
 
             // Wrap if necessary.
-            if (lineWidth + tokenWidth + delimWidth > viewport.width)
+            if (lineWidth + tokenWidth + delimWidth > clip.width)
             {
                 // Add line-height to vertical cursor.
                 yPos += size;
 
                 // Determine horizontal position and width.
-                int hWhitespace = viewport.width - lineWidth;
-                int xPos = viewport.x;
+                int hWhitespace = clip.width - lineWidth;
+                int xPos = clip.x;
                 if (hAlign == ALIGN_HCENTER)
                 {
                     xPos += hWhitespace / 2;
@@ -857,8 +857,8 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
             lineWidth = getTokenWidth(token, tokenLength, size, scale);
             
             // Determine horizontal position and width.
-            int xPos = viewport.x;
-            int hWhitespace = viewport.width - lineWidth;
+            int xPos = clip.x;
+            int hWhitespace = clip.width - lineWidth;
             if (hAlign == ALIGN_HCENTER)
             {
                 xPos += hWhitespace / 2;
@@ -880,8 +880,8 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
     if (wrap)
     {
         // Record the size of the last line.
-        int hWhitespace = viewport.width - lineWidth;
-        int xPos = viewport.x;
+        int hWhitespace = clip.width - lineWidth;
+        int xPos = clip.x;
         if (hAlign == ALIGN_HCENTER)
         {
             xPos += hWhitespace / 2;
@@ -895,9 +895,9 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
     }
 
     int x = INT_MAX;
-    int y = viewport.y;
+    int y = clip.y;
     unsigned int width = 0;
-    int height = yPos - viewport.y;
+    int height = yPos - clip.y;
 
     // Calculate top of text without clipping.
     int vWhitespace = viewportHeight - height;
@@ -914,10 +914,10 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
     int clippedBottom = 0;
     if (!ignoreClip)
     {
-        // Trim rect to fit text that would actually be drawn within the given viewport.
-        if (y >= viewport.y)
+        // Trim rect to fit text that would actually be drawn within the given clip.
+        if (y >= clip.y)
         {
-            // Text goes off the bottom of the viewport.
+            // Text goes off the bottom of the clip.
             clippedBottom = (height - viewportHeight) / size + 1;
             if (clippedBottom > 0)
             {
@@ -938,8 +938,8 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
         }
         else
         {
-            // Text goes above the top of the viewport.
-            clippedTop = (viewport.y - y) / size + 1;
+            // Text goes above the top of the clip.
+            clippedTop = (clip.y - y) / size + 1;
             if (clippedTop < 0)
             {
                 clippedTop = 0;
@@ -995,10 +995,10 @@ void Font::measureText(const char* text, const Rectangle& viewport, unsigned int
 
     if (!ignoreClip)
     {
-        // Guarantee that the output rect will fit within the viewport.
-        out->x = (x >= viewport.x)? x : viewport.x;
-        out->y = (y >= viewport.y)? y : viewport.y;
-        out->width = (width <= viewport.width)? width : viewport.width;
+        // Guarantee that the output rect will fit within the clip.
+        out->x = (x >= clip.x)? x : clip.x;
+        out->y = (y >= clip.y)? y : clip.y;
+        out->width = (width <= clip.width)? width : clip.width;
         out->height = (height <= viewportHeight)? height : viewportHeight;
     }
     else
@@ -1563,7 +1563,7 @@ void Font::addLineInfo(const Rectangle& area, int lineWidth, int lineLength, Jus
     }
 }
 
-SpriteBatch* Font::getSpriteBatch()
+SpriteBatch* Font::getSpriteBatch() const
 {
     return _batch;
 }

gameplay/src/Font.h

@@ -133,6 +133,7 @@ public:
      * @param y The viewport y position to draw text at.
      * @param color The color of text.
      * @param size The size to draw text (0 for default size).
+     * @param rightToLeft Whether to draw text from right to left.
      */
     void drawText(const char* text, int x, int y, const Vector4& color, unsigned int size = 0, bool rightToLeft = false);
 
@@ -156,7 +157,7 @@ public:
      * Measures a string's width and height without alignment, wrapping or clipping.
      *
      * @param text The text to measure.
-     * @param size
+     * @param size The font height to scale to.
      * @param widthOut Destination for the text's width.
      * @param heightOut Destination for the text's height.
      */
@@ -166,9 +167,9 @@ public:
      * Measures a string's bounding box after alignment, wrapping and clipping within a viewport.
      *
      * @param text The text to measure.
+     * @param clip The clip rectangle.
+     * @param size The font height to scale to.
      * @param out Destination rectangle to store the bounds in.
-     * @param viewport The viewport area to align, wrap and clip text within while measuring.
-     * @param scale The scaling factor to apply.
      * @param justify Justification of text within the viewport.
      * @param wrap Whether to measure text with wrapping applied.
      * @param ignoreClip Whether to clip 'out' to the viewport.  Set false for the bounds of what would actually be drawn
@@ -189,8 +190,21 @@ public:
     void getLocationAtIndex(const char* text, const Rectangle& clip, unsigned int size, Vector2* outLocation, const unsigned int destIndex,
                             Justify justify = ALIGN_TOP_LEFT, bool wrap = true, bool rightToLeft = false);
 
-    SpriteBatch* getSpriteBatch();
+    /**
+     * Gets the sprite batch for this Font.
+     * 
+     * @return The sprite batch for this Font.
+     */
+    SpriteBatch* getSpriteBatch() const;
 
+    /**
+     * Gets the Justify value from the given string.
+     * Returns ALIGN_TOP_LEFT if the string is unrecognized.
+     * 
+     * @param justify The string such as "ALIGN_HCENTER" or "ALIGN_VCENTER_RIGHT".
+     * 
+     * @return The Justify value.
+     */
     static Justify getJustifyFromString(const char* justify);
 
 

gameplay/src/Joint.h

@@ -70,8 +70,17 @@ protected:
      */
     void setInverseBindPose(const Matrix& m);
 
+    /**
+     * Updates the joint matrix.
+     * 
+     * @param bindShape The bind shape matrix.
+     * @param matrixPalette The matrix palette to update.
+     */
     void updateJointMatrix(const Matrix& bindShape, Vector4* matrixPalette);
 
+    /**
+     * Called when this Joint's transform changes.
+     */
     void transformChanged();
 
 private:

gameplay/src/Node.h

@@ -402,7 +402,18 @@ public:
      */
     void setModel(Model* model);
 
+    /**
+     * Returns the pointer to this node's form.
+     * 
+     * @return The pointer to this node's form or NULL.
+     */
     Form* getForm() const;
+
+    /**
+     * Assigns a form to this node.
+     * 
+     * @param form The form pointer. May be NULL.
+     */
     void setForm(Form* form);
 
     /**

gameplay/src/PhysicsCharacter.h

@@ -155,7 +155,7 @@ public:
      *
      * @param name Animation name, or NULL to stop all character animations on the given layer.
      * @param flags Animation flags from the AnimationFlags enumeration.
-     * @param speed Optional animation speed (default is 1.0).
+     * @param animationSpeed Optional animation speed (default is 1.0).
      * @param blendDuration Optional number of milliseconds to crossfade between the
      *      currently playing animation on the given layer and the new animation.
      * @param layer Optional animation layer.

gameplay/src/Platform.h

@@ -119,8 +119,28 @@ public:
      */
     static void displayKeyboard(bool display);
 
+    /**
+     * Touch callback on touch events. This method handles passing the touch event to the form or to the game.
+     *
+     * @param evt The touch event that occurred.
+     * @param x The x position of the touch in pixels. Left edge is zero.
+     * @param y The y position of the touch in pixels. Top edge is zero.
+     * @param contactIndex The order of occurrence for multiple touch contacts starting at zero.
+     *
+     * @see Touch::TouchEvent
+     */
     static void touchEventInternal(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
+    /**
+     * Keyboard callback on keyPress events.
+     *
+     * @param evt The key event that occured.
+     * @param key If evt is KEY_PRESS or KEY_RELEASE then key is the key code from Keyboard::Key.
+     *            If evt is KEY_CHAR then key is the unicode value of the character.
+     * 
+     * @see Keyboard::KeyEvent
+     * @see Keyboard::Key
+     */
     static void keyEventInternal(Keyboard::KeyEvent evt, int key);
 
     /**

gameplay/src/RadioButton.h

@@ -120,7 +120,7 @@ protected:
     /**
      * Clear the _selected flag of all radio buttons in the given group.
      *
-     * @param groupID The group to clear.
+     * @param groupId The group to clear.
      */
     static void clearSelected(const std::string& groupId);
 

gameplay/src/Ref.h

@@ -50,6 +50,11 @@ protected:
      */
     Ref();
 
+    /**
+     * Copy constructor.
+     * 
+     * @param copy The Ref object to copy.
+     */
     Ref(const Ref& copy);
 
     /**

gameplay/src/Slider.h

@@ -81,7 +81,7 @@ public:
      * Set this slider's value.  The new value will be clamped to fit within
      * the slider's minimum and maximum values.
      *
-     * @param The new value.
+     * @param value The new value.
      */
     void setValue(float value);
 

gameplay/src/Transform.h

@@ -736,8 +736,22 @@ protected:
         long cookie;
     };
 
+    /**
+     * Marks this transform as dirty and fires transformChanged().
+     */
     void dirty();
+
+    /**
+     * Called when the transform changes.
+     */
     virtual void transformChanged();
+
+    /**
+     * Copies from data from this node into transform for the purpose of cloning.
+     * 
+     * @param transform The transform to copy into.
+     * @param context The clone context.
+     */
     void cloneInto(Transform* transform, NodeCloneContext &context) const;
 
     Vector3 _scale;