From 3ceeca968fe3c6ac5414ea10a543c925c2a266ef Mon Sep 17 00:00:00 2001 From: Aloshi Date: Fri, 24 Jan 2014 16:21:10 -0600 Subject: [PATCH] Updated/added comments. --- src/ThemeData.h | 2 -- src/animations/LambdaAnimation.h | 1 + src/components/AsyncReqComponent.h | 30 ++++++++++--------- src/components/DateTimeComponent.h | 11 +++++-- src/components/ImageComponent.cpp | 6 +--- src/components/ImageComponent.h | 45 ++++++++++++++++++++--------- src/components/NinePatchComponent.h | 15 ++++++++-- src/components/RatingComponent.h | 11 +++++-- src/components/SliderComponent.h | 1 + src/components/SwitchComponent.h | 2 ++ src/components/TextComponent.h | 7 ++++- src/components/TextEditComponent.h | 1 + src/platform.h | 2 +- src/resources/Font.h | 4 +++ src/resources/TextureResource.h | 3 ++ src/views/ViewController.h | 1 + src/views/gamelist/IGameListView.h | 5 +--- 17 files changed, 101 insertions(+), 46 deletions(-) diff --git a/src/ThemeData.h b/src/ThemeData.h index e459ec6a4..19743636f 100644 --- a/src/ThemeData.h +++ b/src/ThemeData.h @@ -124,8 +124,6 @@ public: BOOLEAN }; - void renderExtras(const std::string& view, Window* window, const Eigen::Affine3f& transform); - // If expectedType is an empty string, will do no type checking. const ThemeElement* getElement(const std::string& view, const std::string& element, const std::string& expectedType) const; diff --git a/src/animations/LambdaAnimation.h b/src/animations/LambdaAnimation.h index d3888c2f1..27c5c1dc3 100644 --- a/src/animations/LambdaAnimation.h +++ b/src/animations/LambdaAnimation.h @@ -2,6 +2,7 @@ #include "Animation.h" +// Useful for simple one-off animations, you can supply the animation's apply(t) method right in the constructor as a lambda. class LambdaAnimation : public Animation { public: diff --git a/src/components/AsyncReqComponent.h b/src/components/AsyncReqComponent.h index dd7417b0a..a239ad3f9 100644 --- a/src/components/AsyncReqComponent.h +++ b/src/components/AsyncReqComponent.h @@ -5,20 +5,24 @@ #include #include -/* Usage example: - std::shared_ptr httpreq = std::make_shared("cdn.garcya.us", "/wp-content/uploads/2010/04/TD250.jpg"); - AsyncReqComponent* req = new AsyncReqComponent(mWindow, httpreq, - [] (std::shared_ptr r) - { - LOG(LogInfo) << "Request completed"; - LOG(LogInfo) << " error, if any: " << r->getErrorMsg(); - }, [] () - { - LOG(LogInfo) << "Request canceled"; - }); +/* + Used to asynchronously run an HTTP request. + Displays a simple animation on the UI to show the application hasn't frozen. Can be canceled by the user pressing B. - mWindow->pushGui(req); - //we can forget about req, since it will always delete itself + Usage example: + std::shared_ptr httpreq = std::make_shared("cdn.garcya.us", "/wp-content/uploads/2010/04/TD250.jpg"); + AsyncReqComponent* req = new AsyncReqComponent(mWindow, httpreq, + [] (std::shared_ptr r) + { + LOG(LogInfo) << "Request completed"; + LOG(LogInfo) << " error, if any: " << r->getErrorMsg(); + }, [] () + { + LOG(LogInfo) << "Request canceled"; + }); + + mWindow->pushGui(req); + //we can forget about req, since it will always delete itself */ class AsyncReqComponent : public GuiComponent diff --git a/src/components/DateTimeComponent.h b/src/components/DateTimeComponent.h index 13b5a5424..0fd5274fc 100644 --- a/src/components/DateTimeComponent.h +++ b/src/components/DateTimeComponent.h @@ -4,9 +4,11 @@ #include #include "../resources/Font.h" +// Used to enter or display a specific point in time. class DateTimeComponent : public GuiComponent { public: + // Display mode will initialize to DISP_DATE. DateTimeComponent(Window* window); void setValue(const std::string& val) override; @@ -23,10 +25,15 @@ public: DISP_RELATIVE_TO_NOW }; + // Set how the point in time will be displayed: + // * DISP_DATE - only display the date. + // * DISP_DATE_TIME - display both the date and the time on that date. + // * DISP_RELATIVE_TO_NOW - intelligently display the point in time relative to right now (e.g. "5 secs ago", "3 minutes ago", "1 day ago". Automatically updates as time marches on. + // The initial value is DISP_DATE. void setDisplayMode(DisplayMode mode); - void setColor(unsigned int color); - void setFont(std::shared_ptr font); + void setColor(unsigned int color); // Text color. + void setFont(std::shared_ptr font); // Font to display with. Default is Font::get(FONT_SIZE_MEDIUM). virtual void applyTheme(const std::shared_ptr& theme, const std::string& view, const std::string& element, unsigned int properties) override; diff --git a/src/components/ImageComponent.cpp b/src/components/ImageComponent.cpp index abb37134a..cb5c32723 100644 --- a/src/components/ImageComponent.cpp +++ b/src/components/ImageComponent.cpp @@ -20,13 +20,9 @@ Eigen::Vector2f ImageComponent::getCenter() const mPosition.y() - (getSize().y() * mOrigin.y()) + getSize().y() / 2); } -ImageComponent::ImageComponent(Window* window, const Eigen::Vector2f& pos, const std::string& path) : GuiComponent(window), +ImageComponent::ImageComponent(Window* window) : GuiComponent(window), mTargetIsMax(false), mFlipX(false), mFlipY(false), mOrigin(0.0, 0.0), mTargetSize(0, 0), mColorShift(0xFFFFFFFF) { - setPosition(pos.x(), pos.y()); - - if(!path.empty()) - setImage(path); } ImageComponent::~ImageComponent() diff --git a/src/components/ImageComponent.h b/src/components/ImageComponent.h index be17ac0cc..2e7b8576b 100644 --- a/src/components/ImageComponent.h +++ b/src/components/ImageComponent.h @@ -12,29 +12,43 @@ class ImageComponent : public GuiComponent { public: - //Creates a new GuiImage at the given location. If given an image, it will be loaded. If maxWidth and/or maxHeight are nonzero, the image will be - //resized to fit. If only one axis is specified, the other will be set in accordance with the image's aspect ratio. If allowUpscale is false, - //the image will only be downscaled, never upscaled (the image's size must surpass at least one nonzero bound). - ImageComponent(Window* window, const Eigen::Vector2f& pos = Eigen::Vector2f::Zero(), const std::string& path = ""); + ImageComponent(Window* window); virtual ~ImageComponent(); - void setImage(std::string path, bool tile = false); //Loads the image at the given filepath. - void setImage(const char* image, size_t length, bool tile = false); //Loads image from memory. - void setImage(const std::shared_ptr& texture); //Use an already existing texture. - void setOrigin(float originX, float originY); //Sets the origin as a percentage of this image (e.g. (0, 0) is top left, (0.5, 0.5) is the center) + //Loads the image at the given filepath. Will tile if tile is true (retrieves texture as tiling, creates vertices accordingly). + void setImage(std::string path, bool tile = false); + //Loads an image from memory. + void setImage(const char* image, size_t length, bool tile = false); + //Use an already existing texture. + void setImage(const std::shared_ptr& texture); + + //Sets the origin as a percentage of this image (e.g. (0, 0) is top left, (0.5, 0.5) is the center) + void setOrigin(float originX, float originY); inline void setOrigin(Eigen::Vector2f origin) { setOrigin(origin.x(), origin.y()); } + + // Resize the image to fit this size. If one axis is zero, scale that axis to maintain aspect ratio. + // If both are non-zero, potentially break the aspect ratio. If both are zero, no resizing. + // Can be set before or after an image is loaded. + // setMaxSize() and setResize() are mutually exclusive. void setResize(float width, float height); inline void setResize(const Eigen::Vector2f& size) { setResize(size.x(), size.y()); } + + // Resize the image to be as large as possible but fit within a box of this size. + // Can be set before or after an image is loaded. + // Never breaks the aspect ratio. setMaxSize() and setResize() are mutually exclusive. void setMaxSize(float width, float height); inline void setMaxSize(const Eigen::Vector2f& size) { setMaxSize(size.x(), size.y()); } + + // Multiply all pixels in the image by this color when rendering. void setColorShift(unsigned int color); - void setFlipX(bool flip); - void setFlipY(bool flip); + void setFlipX(bool flip); // Mirror on the X axis. + void setFlipY(bool flip); // Mirror on the Y axis. - //You can get the rendered size of the ImageComponent with getSize(). + // Returns the size of the current texture, or (0, 0) if none is loaded. May be different than drawn size (use getSize() for that). Eigen::Vector2i getTextureSize() const; + // Returns the center point of the image (takes origin into account). Eigen::Vector2f getCenter() const; bool hasImage(); @@ -49,9 +63,14 @@ private: bool mFlipX, mFlipY, mTargetIsMax; + // Calculates the correct mSize from our resizing information (set by setResize/setMaxSize). + // Used internally whenever the resizing parameters or texture change. void resize(); - void buildImageArray(int x, int y, GLfloat* points, GLfloat* texs, float percentageX = 1, float percentageY = 1); //writes 12 GLfloat points and 12 GLfloat texture coordinates to a given array at a given position - void drawImageArray(GLfloat* points, GLfloat* texs, GLubyte* colors, unsigned int count = 6); //draws the given set of points and texture coordinates, number of coordinate pairs may be specified (default 6) + + // Writes 12 GLfloat points and 12 GLfloat texture coordinates to a given array at a given position. + void buildImageArray(int x, int y, GLfloat* points, GLfloat* texs, float percentageX = 1, float percentageY = 1); + // Draws the given set of points and texture coordinates, number of coordinate pairs may be specified. + void drawImageArray(GLfloat* points, GLfloat* texs, GLubyte* colors, unsigned int count = 6); unsigned int mColorShift; diff --git a/src/components/NinePatchComponent.h b/src/components/NinePatchComponent.h index 471490cd4..aebbcd1eb 100644 --- a/src/components/NinePatchComponent.h +++ b/src/components/NinePatchComponent.h @@ -3,6 +3,17 @@ #include "../GuiComponent.h" #include "../resources/TextureResource.h" +// Display an image in a way so that edges don't get too distorted no matter the final size. Useful for UI elements like backgrounds, buttons, etc. +// This is accomplished by splitting an image into 9 pieces: +// ___________ +// |_1_|_2_|_3_| +// |_4_|_5_|_6_| +// |_7_|_8_|_9_| + +// Corners (1, 3, 7, 9) will not be stretched at all. +// Borders (2, 4, 6, 8) will be stretched along one axis (2 and 8 horizontally, 4 and 6 vertically). +// The center (5) will be stretched. + class NinePatchComponent : public GuiComponent { public: @@ -15,8 +26,8 @@ public: void fitTo(Eigen::Vector2f size, Eigen::Vector3f position = Eigen::Vector3f::Zero(), Eigen::Vector2f padding = Eigen::Vector2f::Zero()); void setImagePath(const std::string& path); - void setEdgeColor(unsigned int edgeColor); - void setCenterColor(unsigned int centerColor); + void setEdgeColor(unsigned int edgeColor); // Apply a color shift to the "edge" parts of the ninepatch. + void setCenterColor(unsigned int centerColor); // Apply a color shift to the "center" part of the ninepatch. virtual void applyTheme(const std::shared_ptr& theme, const std::string& view, const std::string& element, unsigned int properties) override; diff --git a/src/components/RatingComponent.h b/src/components/RatingComponent.h index 5a40e741b..4b5da45c2 100644 --- a/src/components/RatingComponent.h +++ b/src/components/RatingComponent.h @@ -3,13 +3,18 @@ #include "../GuiComponent.h" #include "../resources/TextureResource.h" +// Used to visually display/edit some sort of "score" - e.g. 5/10, 3/5, etc. +// setSize(x, y) works a little differently than you might expect: +// * (0, y != 0) - x will be automatically calculated (5*y). +// * (x != 0, 0) - y will be automatically calculated (x/5). +// * (x != 0, y != 0) - you better be sure x = y*5 class RatingComponent : public GuiComponent { public: RatingComponent(Window* window); std::string getValue() const override; - void setValue(const std::string& value) override; + void setValue(const std::string& value) override; // Should be a normalized float (in the range [0..1]) - if it's not, it will be clamped. bool input(InputConfig* config, Input input) override; void render(const Eigen::Affine3f& parentTrans); @@ -29,7 +34,7 @@ private: Eigen::Vector2f tex; } mVertices[12]; - std::shared_ptr mFilledTexture; - std::shared_ptr mUnfilledTexture; + std::shared_ptr mFilledTexture; // Must be square (width == height)! + std::shared_ptr mUnfilledTexture; // Must be square (width == height)! }; diff --git a/src/components/SliderComponent.h b/src/components/SliderComponent.h index d39ef6cbf..b5e82c5f7 100644 --- a/src/components/SliderComponent.h +++ b/src/components/SliderComponent.h @@ -5,6 +5,7 @@ class TextCache; class Font; +// Used to display/edit a value between some min and max values. class SliderComponent : public GuiComponent { public: diff --git a/src/components/SwitchComponent.h b/src/components/SwitchComponent.h index 13ab441fb..b3fcaac05 100644 --- a/src/components/SwitchComponent.h +++ b/src/components/SwitchComponent.h @@ -2,6 +2,8 @@ #include "../GuiComponent.h" +// A very simple "on/off" switch. +// Should hopefully be switched to use images instead of text in the future. class SwitchComponent : public GuiComponent { public: diff --git a/src/components/TextComponent.h b/src/components/TextComponent.h index e9906f67b..ad786d548 100644 --- a/src/components/TextComponent.h +++ b/src/components/TextComponent.h @@ -6,6 +6,11 @@ class ThemeData; +// Used to display text. +// TextComponent::setSize(x, y) works a little differently than most components: +// * (0, 0) - will automatically calculate a size that fits the text on one line (expand horizontally) +// * (x != 0, 0) - wrap text so that it does not reach beyond x. Will automatically calculate a vertical size (expand vertically). +// * (x != 0, y <= fontHeight) - will truncate text so it fits within this box. class TextComponent : public GuiComponent { public: @@ -16,7 +21,7 @@ public: void onSizeChanged() override; void setText(const std::string& text); void setColor(unsigned int color); - void setCentered(bool center); //Default is uncentered. + void setCentered(bool center); // Will horizontally center text. Default is false. void render(const Eigen::Affine3f& parentTrans) override; diff --git a/src/components/TextEditComponent.h b/src/components/TextEditComponent.h index d9117597a..9746ca95f 100644 --- a/src/components/TextEditComponent.h +++ b/src/components/TextEditComponent.h @@ -6,6 +6,7 @@ class Font; class TextCache; +// Used to enter text. class TextEditComponent : public GuiComponent { public: diff --git a/src/platform.h b/src/platform.h index 011d7b81a..a0bb68251 100644 --- a/src/platform.h +++ b/src/platform.h @@ -1,4 +1,4 @@ -//the Makefiles define these via command line +//the Makefile defines one of these: //#define USE_OPENGL_ES //#define USE_OPENGL_DESKTOP diff --git a/src/resources/Font.h b/src/resources/Font.h index 8cc3f501b..a9a1d3e82 100644 --- a/src/resources/Font.h +++ b/src/resources/Font.h @@ -98,6 +98,10 @@ private: const std::string mPath; }; +// Used to store a sort of "pre-rendered" string. +// When a TextCache is constructed (Font::buildTextCache()), the vertices and texture coordinates of the string are calculated and stored in the TextCache object. +// Rendering a TextCache (Font::renderTextCache) every frame is MUCH faster than calling Font::drawText() and its variants. +// Keep in mind you still need the Font object to render a TextCache (as the Font holds the OpenGL texture), and if a Font changes your TextCache may become invalid. class TextCache { public: diff --git a/src/resources/TextureResource.h b/src/resources/TextureResource.h index 64f4036b6..2ec75e43f 100644 --- a/src/resources/TextureResource.h +++ b/src/resources/TextureResource.h @@ -7,6 +7,8 @@ #include "../platform.h" #include GLHEADER +// An OpenGL texture. +// Automatically recreates the texture with renderer deinit/reinit. class TextureResource : public IReloadable { public: @@ -21,6 +23,7 @@ public: Eigen::Vector2i getSize() const; void bind() const; + // Warning: will NOT correctly reinitialize when this texture is reloaded (e.g. ES starts/stops playing a game). void initFromMemory(const char* image, size_t length); private: diff --git a/src/views/ViewController.h b/src/views/ViewController.h index b2225275e..fdb6332d1 100644 --- a/src/views/ViewController.h +++ b/src/views/ViewController.h @@ -5,6 +5,7 @@ class SystemData; +// Used to smoothly transition the camera between multiple views (e.g. from system to system, from gamelist to gamelist). class ViewController : public GuiComponent { public: diff --git a/src/views/gamelist/IGameListView.h b/src/views/gamelist/IGameListView.h index a2ec8b5ab..b2229dfd7 100644 --- a/src/views/gamelist/IGameListView.h +++ b/src/views/gamelist/IGameListView.h @@ -8,10 +8,7 @@ class GuiComponent; class FileData; class ThemeData; -//IGameListView needs to know: -// What theme data to use -// The root FileData for the tree it should explore - +// This is an interface that defines the minimum for a GameListView. class IGameListView : public GuiComponent { public: