From 9f86bd47f7384f8faaa539d5d38764cd5e31db14 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 9 Apr 2011 17:09:30 -0400 Subject: [PATCH] [sm130futures] doxygen --- src/Actor.h | 58 +++++++++++++++++++++++++++++++++++++----- src/PlayerStageStats.h | 7 +++++ src/ScreenEdit.h | 28 ++++++++++++-------- src/ScreenJukebox.h | 3 +-- src/ScreenOptions.h | 20 ++++++++++++--- src/ScreenTestFonts.h | 8 +++--- src/Sprite.h | 8 +++++- 7 files changed, 104 insertions(+), 28 deletions(-) diff --git a/src/Actor.h b/src/Actor.h index e0795e310f..45d080dabe 100644 --- a/src/Actor.h +++ b/src/Actor.h @@ -99,6 +99,9 @@ class Actor : public MessageSubscriber public: /** @brief Set up the Actor with its initial settings. */ Actor(); + /** + * @brief Copy a new Actor to the old one. + * @param cpy the new Actor to use in place of this one. */ Actor( const Actor &cpy ); virtual ~Actor(); virtual Actor *Copy() const; @@ -218,11 +221,35 @@ public: float aux; }; - void Draw(); // calls, EarlyAbortDraw, BeginDraw, DrawPrimitives, EndDraw - virtual bool EarlyAbortDraw() const { return false; } // return true to early abort drawing of this Actor - virtual void BeginDraw(); // pushes transform onto world matrix stack - virtual void SetGlobalRenderStates(); // Actor should call this at beginning of their DrawPrimitives() - virtual void SetTextureRenderStates(); // Actor should call this after setting a texture + /** + * @brief Calls multiple functions for drawing the Actors. + * + * It calls the following in order: + * -# EarlyAbortDraw + * -# BeginDraw + * -# DrawPrimitives + * -# EndDraw + */ + void Draw(); + /** + * @brief Allow the Actor to be aborted early. + * + * Subclasses may wish to overwrite this to allow for + * aborted actors. + * @return false, as by default Actors shouldn't be aborted on drawing. */ + virtual bool EarlyAbortDraw() const { return false; } + /** @brief Start the drawing and push the transform on the world matrix stack. */ + virtual void BeginDraw(); + /** + * @brief Set the global rendering states of this Actor. + * + * This should be called at the beginning of an Actor's DrawPrimitives() call. */ + virtual void SetGlobalRenderStates(); + /** + * @brief Set the texture rendering states of this Actor. + * + * This should be called after setting a texture for the Actor. */ + virtual void SetTextureRenderStates(); /** * @brief Draw the primitives of the Actor. * @@ -331,9 +358,26 @@ public: * @brief Retrieve the zoom factor for the z coordinate of the Actor. * @return the zoom factor for the z coordinate of the Actor. */ float GetZoomZ() const { return DestTweenState().scale.z; } - void SetZoom( float zoom ) { DestTweenState().scale.x = zoom; DestTweenState().scale.y = zoom; DestTweenState().scale.z = zoom; } + /** + * @brief Set the zoom factor for all dimensions of the Actor. + * @param zoom the zoom factor for all dimensions. */ + void SetZoom( float zoom ) + { + DestTweenState().scale.x = zoom; + DestTweenState().scale.y = zoom; + DestTweenState().scale.z = zoom; + } + /** + * @brief Set the zoom factor for the x dimension of the Actor. + * @param zoom the zoom factor for the x dimension. */ void SetZoomX( float zoom ) { DestTweenState().scale.x = zoom; } + /** + * @brief Set the zoom factor for the y dimension of the Actor. + * @param zoom the zoom factor for the y dimension. */ void SetZoomY( float zoom ) { DestTweenState().scale.y = zoom; } + /** + * @brief Set the zoom factor for the z dimension of the Actor. + * @param zoom the zoom factor for the z dimension. */ void SetZoomZ( float zoom ) { DestTweenState().scale.z = zoom; } void ZoomTo( float fX, float fY ) { ZoomToWidth(fX); ZoomToHeight(fY); } void ZoomToWidth( float zoom ) { SetZoomX( zoom / GetUnzoomedWidth() ); } @@ -420,7 +464,7 @@ public: enum StretchType { fit_inside, /**< Have the Actor fit inside its parent, using the smaller zoom. */ - cover /**, Have the Actor cover its parent, using the larger zoom. */ + cover /**< Have the Actor cover its parent, using the larger zoom. */ }; void ScaleToCover( const RectF &rect ) { ScaleTo( rect, cover ); } diff --git a/src/PlayerStageStats.h b/src/PlayerStageStats.h index f378ac48a8..5c6a944c5c 100644 --- a/src/PlayerStageStats.h +++ b/src/PlayerStageStats.h @@ -12,9 +12,13 @@ struct lua_State; class PlayerStageStats { public: + /** @brief Set up the PlayerStageStats with default values. */ PlayerStageStats() { Init(); } void Init(); + /** + * @brief Add stats from one PlayerStageStats to another. + * @param other the other stats to add to this one. */ void AddStats( const PlayerStageStats& other ); // accumulate Grade GetGrade() const; @@ -58,8 +62,11 @@ public: /** @brief The Player's current miss combo. */ int m_iCurMissCombo; int m_iCurScoreMultiplier; + /** @brief The player's current score. */ int m_iScore; + /** @brief The theoretically highest score the Player could have at this point. */ int m_iCurMaxScore; + /** @brief The maximum score the Player can get this goaround. */ int m_iMaxScore; /** diff --git a/src/ScreenEdit.h b/src/ScreenEdit.h index d16606fd47..664162fff4 100644 --- a/src/ScreenEdit.h +++ b/src/ScreenEdit.h @@ -24,12 +24,13 @@ const int NUM_EDIT_BUTTON_COLUMNS = 10; struct MenuDef; +/** @brief What is going on with the Editor? */ enum EditState { - STATE_EDITING, - STATE_RECORDING, - STATE_RECORDING_PAUSED, - STATE_PLAYING, + STATE_EDITING, /**< The person is making adjustments to the Steps. */ + STATE_RECORDING, /**< The person is recording some Steps live. */ + STATE_RECORDING_PAUSED, /**< The person has temporarily paused the recording of Steps. */ + STATE_PLAYING, /**< The person is just trying out the Steps. */ NUM_EditState, EditState_Invalid }; @@ -56,8 +57,8 @@ enum EditButton EDIT_BUTTON_REMOVE_NOTE, // These are modifiers to change the present tap note. - EDIT_BUTTON_CYCLE_TAP_LEFT, - EDIT_BUTTON_CYCLE_TAP_RIGHT, + EDIT_BUTTON_CYCLE_TAP_LEFT, /**< Rotate the available tap notes once to the "left". */ + EDIT_BUTTON_CYCLE_TAP_RIGHT, /**< Rotate the available tap notes once to the "right". */ EDIT_BUTTON_SCROLL_UP_LINE, EDIT_BUTTON_SCROLL_UP_PAGE, @@ -130,13 +131,13 @@ enum EditButton // This modifies offset, BPM, and stop segment changes. EDIT_BUTTON_ADJUST_FINE, - EDIT_BUTTON_SAVE, + EDIT_BUTTON_SAVE, /**< Save the present changes into the chart. */ - EDIT_BUTTON_UNDO, + EDIT_BUTTON_UNDO, /**< Undo a recent change. */ EDIT_BUTTON_ADD_COURSE_MODS, - EDIT_BUTTON_SWITCH_PLAYERS, + EDIT_BUTTON_SWITCH_PLAYERS, /**< Allow entering notes for a different Player. */ NUM_EditButton, // leave this at the end EditButton_Invalid @@ -254,12 +255,17 @@ protected: // The location we were at when shift was pressed, or -1 when shift isn't pressed: int m_iShiftAnchor; + /** @brief The NoteData that has been cut or copied. */ NoteData m_Clipboard; bool m_bHasUndo; - // TODO: convert this into a stack of NoteData objs for multi-state undo -aj + /** + * @brief The NoteData as it once just one action prior. + * + * TODO: Convert this into a stack or vector of NoteData to allow multiple undos. -aj + * TODO: Look into a redo option. -aj */ NoteData m_Undo; - // TODO: also maybe have a redo stack/option -aj + /** @brief Has the NoteData been changed such that a user should be prompted to save? */ bool m_bDirty; RageSound m_soundAddNote; diff --git a/src/ScreenJukebox.h b/src/ScreenJukebox.h index 92bd6f059f..a822525b09 100644 --- a/src/ScreenJukebox.h +++ b/src/ScreenJukebox.h @@ -1,11 +1,10 @@ -/* ScreenJukebox - Plays whole songs continuously. */ - #ifndef ScreenJukebox_H #define ScreenJukebox_H #include "ScreenGameplayNormal.h" class CourseEntry; +/** @brief Plays whole songs continuously. */ class ScreenJukebox : public ScreenGameplayNormal { public: diff --git a/src/ScreenOptions.h b/src/ScreenOptions.h index d08ab4dc7b..f78ab23116 100644 --- a/src/ScreenOptions.h +++ b/src/ScreenOptions.h @@ -26,7 +26,9 @@ InputMode StringToInputMode( const RString& str ); /** @brief A custom foreach loop for the player options for each player. */ #define FOREACH_OptionsPlayer( pn ) \ - for( PlayerNumber pn=GetNextHumanPlayer((PlayerNumber)-1); pn!=PLAYER_INVALID && (m_InputMode==INPUTMODE_INDIVIDUAL || pn==0); pn=GetNextHumanPlayer(pn) ) + for( PlayerNumber pn=GetNextHumanPlayer((PlayerNumber)-1); \ + pn!=PLAYER_INVALID && (m_InputMode==INPUTMODE_INDIVIDUAL || pn==0); \ + pn=GetNextHumanPlayer(pn) ) /** @brief A grid of options; the selected option is drawn with a highlight rectangle. */ class ScreenOptions : public ScreenWithMenuElements @@ -53,7 +55,8 @@ protected: virtual void ExportOptions( int iRow, const vector &vpns ) = 0; void RestartOptions(); - void GetWidthXY( PlayerNumber pn, int iRow, int iChoiceOnRow, int &iWidthOut, int &iXOut, int &iYOut ) const; + void GetWidthXY( PlayerNumber pn, int iRow, int iChoiceOnRow, + int &iWidthOut, int &iXOut, int &iYOut ) const; RString GetExplanationText( int iRow ) const; void RefreshIcons( int iRow, PlayerNumber pn ); void PositionCursor( PlayerNumber pn ); @@ -67,10 +70,18 @@ protected: void ChangeValueInRowRelative( int iRow, PlayerNumber pn, int iDelta, bool bRepeat ); void ChangeValueInRowAbsolute( int iRow, PlayerNumber pn, int iChoiceIndex, bool bRepeat ); - virtual void AfterChangeValueInRow( int iRow, PlayerNumber pn ); // override this to detect when the value in a row has changed + /** + * @brief Perform an action after a row has changed its value. + * + * Override this to detect when the value in a row has changed. */ + virtual void AfterChangeValueInRow( int iRow, PlayerNumber pn ); bool MoveRowRelative( PlayerNumber pn, int iDir, bool bRepeat ); bool MoveRowAbsolute( PlayerNumber pn, int iRow ); - virtual void AfterChangeRow( PlayerNumber pn ); // override this to detect when the row has changed + /** + * @brief Perform an action after moving to a new row. + * + * Override this to detect when the row has changed. */ + virtual void AfterChangeRow( PlayerNumber pn ); virtual void AfterChangeValueOrRow( PlayerNumber pn ); virtual void MenuBack( const InputEventPlus &input ); @@ -107,6 +118,7 @@ protected: // derived classes need access to these bool m_bWasOnExit[NUM_PLAYERS]; /** @brief True if at least one player pressed Start after selecting the song. + * * TRICKY: People hold Start to get to PlayerOptions, then the repeat events * cause them to zip to the bottom. So, ignore Start repeat events until * we've seen one first pressed event. */ diff --git a/src/ScreenTestFonts.h b/src/ScreenTestFonts.h index 16c9e2fd19..c6cdf7e2cf 100644 --- a/src/ScreenTestFonts.h +++ b/src/ScreenTestFonts.h @@ -1,5 +1,3 @@ -/* ScreenTestFonts - Display and test fonts. */ - #ifndef SCREEN_TEST_FONTS_H #define SCREEN_TEST_FONTS_H @@ -7,6 +5,7 @@ #include "BitmapText.h" #include "Quad.h" +/** @brief Display and test fonts. */ class ScreenTestFonts: public Screen { public: @@ -20,7 +19,10 @@ private: void SetText( RString sText ); void SetFont( RString sFont ); - RString m_sCurText, m_sFont; + /** @brief The current text to display. */ + RString m_sCurText; + /** @brief The current font in use. */ + RString m_sFont; BitmapText txt, font; Quad Vline, Hline; }; diff --git a/src/Sprite.h b/src/Sprite.h index 4b53474d8f..69e28ea790 100644 --- a/src/Sprite.h +++ b/src/Sprite.h @@ -99,7 +99,13 @@ private: EffectMode m_EffectMode; bool m_bUsingCustomTexCoords; bool m_bSkipNextUpdate; - float m_CustomTexCoords[8]; // (x,y) * 4: top left, bottom left, bottom right, top right + /** + * @brief Set up the coordinates for the texture. + * + * The first two parameters are the (x, y) coordinates for the top left. + * The remaining six are for the (x, y) coordinates for bottom left, + * bottom right, and top right respectively. */ + float m_CustomTexCoords[8]; // Remembered clipped dimensions are applied on Load(). // -1 means no remembered dimensions;