libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2025-05-13 17:46:22 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DOXYGEN: Review of high prio files from graphics

Browse Source 
Editing doxygen comments in:

- cursorman.h
- font.h
- managed_surface.h
- pixelformat.h
- surface.h
This commit is contained in:
Bartosz Gentkowski 2020-11-25 01:52:40 +01:00 committed by Thierry Crozat
parent ee8598ba2c
commit 529b64d8cd
6 changed files with 629 additions and 428 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/doxygen/groups.dox
View File

@ -15,6 +15,13 @@
/** /**
@defgroup graphics Graphics API
@brief API related to on-screen graphics - surfaces, pixels, cursors, fonts, palettes, and renderers.
*/
/**
@defgroup image Image API @defgroup image Image API
@brief API of various image decoders used in engines. @brief API of various image decoders used in engines.

138
graphics/cursorman.h
View File

@ -31,19 +31,28 @@
namespace Graphics { namespace Graphics {
/**
* @defgroup graphics_cursorman Cursor manager
* @ingroup graphics
*
* @brief The CursorManager class for managing the behavior of the mouse cursor.
*
* @{
*/
class CursorManager : public Common::Singleton<CursorManager> { class CursorManager : public Common::Singleton<CursorManager> {
public: public:
/** Query whether the mouse cursor is visible. */ /** Return whether the mouse cursor is visible. */
bool isVisible(); bool isVisible();
/** /**
* Show or hide the mouse cursor. * Show or hide the mouse cursor.
* *
* This function does not call OSystem::updateScreen, when visible is true. * This function does not call OSystem::updateScreen, when visible is true.
* This fact might result in a non visible mouse cursor if the caller does * You may need to call OSystem::updateScreen after a call to showMouse(true)
* not call OSystem::updateScreen itself after a showMouse(true) call. * to ensure that the mouse cursor becomes visible.
* *
* TODO: We might want to reconsider this behavior, it might be confusing * @todo We might want to reconsider this behavior, it might be confusing
* for the user to call OSystem::updateScreen separately, on the other * for the user to call OSystem::updateScreen separately, on the other
* hand OSystem::updateScreen might as well display unwanted changes on * hand OSystem::updateScreen might as well display unwanted changes on
* the screen. Another alternative would be to let the backend worry * the screen. Another alternative would be to let the backend worry
@ -54,22 +63,24 @@ public:
bool showMouse(bool visible); bool showMouse(bool visible);
/** /**
* Push a new cursor onto the stack, and set it in the backend. A local * Push a new cursor onto the stack, and set it in the backend.
* copy will be made of the cursor data, so the original buffer can be
* safely freed afterwards.
* *
* @param buf the new cursor data * A local copy of the cursor data will be made, so the original buffer
* @param w the width * can be safely freed afterwards.
* @param h the height *
* @param hotspotX the hotspot X coordinate * @param buf New cursor data.
* @param hotspotY the hotspot Y coordinate * @param w Width.
* @param keycolor the color value for the transparent color. This may not exceed * @param h Height.
* @param hotspotX Hotspot X coordinate.
* @param hotspotY Hotspot Y coordinate.
* @param keycolor Color value for the transparent color. This cannot exceed
* the maximum color value as defined by format. * the maximum color value as defined by format.
* @param dontScale Whether the cursor should never be scaled. An exception are high ppi displays, where the cursor * @param dontScale Whether the cursor should never be scaled. An exception are high PPI displays, where the cursor
* would be too small to notice otherwise, these are allowed to scale the cursor anyway. * would be too small to notice otherwise. These are allowed to scale the cursor anyway.
* @param format a pointer to the pixel format which the cursor graphic uses, * @param format Pointer to the pixel format that the cursor graphic uses.
* CLUT8 will be used if this is NULL or not specified. * CLUT8 will be used if this is null or not specified.
* @note It is ok for the buffer to be a NULL pointer. It is sometimes *
* @note It is acceptable for the buffer to be a null pointer. It is sometimes
* useful to push a "dummy" cursor and modify it later. The * useful to push a "dummy" cursor and modify it later. The
* cursor will be added to the stack, but not to the backend. * cursor will be added to the stack, but not to the backend.
*/ */
@ -77,41 +88,46 @@ public:
/** /**
* Pop a cursor from the stack, and restore the previous one to the * Pop a cursor from the stack, and restore the previous one to the
* backend. If there is no previous cursor, the cursor is hidden. * backend.
*
* If there is no previous cursor, the cursor is hidden.
*/ */
void popCursor(); void popCursor();
/** /**
* Replace the current cursor on the stack. If the stack is empty, the * Replace the current cursor on the stack.
* cursor is pushed instead. It's a slightly more optimized way of
* popping the old cursor before pushing the new one.
* *
* @param buf the new cursor data * If the stack is empty, the cursor is pushed instead. This is a slightly
* @param w the width * more optimized way of popping the old cursor before pushing the new one.
* @param h the height *
* @param hotspotX the hotspot X coordinate * @param buf New cursor data.
* @param hotspotY the hotspot Y coordinate * @param w Width.
* @param keycolor the color value for the transparent color. This may not exceed * @param h Height.
* @param hotspotX Hotspot X coordinate.
* @param hotspotY Hotspot Y coordinate.
* @param keycolor Color value for the transparent color. This cannot exceed
* the maximum color value as defined by format. * the maximum color value as defined by format.
* @param dontScale Whether the cursor should never be scaled. An exception are high ppi displays, where the cursor * @param dontScale Whether the cursor should never be scaled. An exception are high PPI displays, where the cursor
* would be too small to notice otherwise, these are allowed to scale the cursor anyway. * would be too small to notice otherwise. These are allowed to scale the cursor anyway.
* @param format a pointer to the pixel format which the cursor graphic uses, * @param format Pointer to the pixel format that the cursor graphic uses,
* CLUT8 will be used if this is NULL or not specified. * CLUT8 will be used if this is null or not specified.
*/ */
void replaceCursor(const void *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, bool dontScale = false, const Graphics::PixelFormat *format = NULL); void replaceCursor(const void *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, bool dontScale = false, const Graphics::PixelFormat *format = NULL);
/** /**
* Replace the current cursor on the stack. If the stack is empty, the * Replace the current cursor on the stack.
* cursor is pushed instead. It's a slightly more optimized way of
* popping the old cursor before pushing the new one.
* *
* @param cursor the new cursor * If the stack is empty, the cursor is pushed instead. This is a slightly
* more optimized way of popping the old cursor before pushing the new one.
*
* @param cursor New cursor.
*/ */
void replaceCursor(const Graphics::Cursor *cursor); void replaceCursor(const Graphics::Cursor *cursor);
/** /**
* Pop all of the cursors and cursor palettes from their respective stacks. * Pop all cursors and cursor palettes from their respective stacks.
* The purpose is to ensure that all unecessary cursors are removed from the *
* The purpose is to ensure that all unnecessary cursors are removed from the
* stack when returning to the launcher from an engine. * stack when returning to the launcher from an engine.
* *
*/ */
@ -120,8 +136,8 @@ public:
/** /**
* Test whether cursor palettes are supported. * Test whether cursor palettes are supported.
* *
* This is just an convenience wrapper for checking for * This is just an convenience wrapper for checking whether
* OSystem::kFeatureCursorPalette to be supported by OSystem. * OSystem::kFeatureCursorPalette is supported by OSystem.
* *
* @see OSystem::kFeatureCursorPalette * @see OSystem::kFeatureCursorPalette
* @see OSystem::hasFeature * @see OSystem::hasFeature
@ -129,7 +145,7 @@ public:
bool supportsCursorPalettes(); bool supportsCursorPalettes();
/** /**
* Enable/Disable the current cursor palette. * Enable or disable the current cursor palette.
* *
* @param disable * @param disable
*/ */
@ -137,15 +153,16 @@ public:
/** /**
* Push a new cursor palette onto the stack, and set it in the backend. * Push a new cursor palette onto the stack, and set it in the backend.
* The palette entries from 'start' till (start+num-1) will be replaced *
* so a full palette updated is accomplished via start=0, num=256. * The palette entries from @p start until @c (start+num-1) will be replaced
* so a full palette update is accomplished via start=0, num=256.
* *
* The palette data is specified in the same interleaved RGB format as * The palette data is specified in the same interleaved RGB format as
* used by all backends. * used by all backends.
* *
* @param colors the new palette data, in interleaved RGB format * @param colors New palette data, in interleaved RGB format.
* @param start the first palette entry to be updated * @param start First palette entry to be updated.
* @param num the number of palette entries to be updated * @param num Number of palette entries to be updated.
* *
* @note If num is zero, the cursor palette is disabled. * @note If num is zero, the cursor palette is disabled.
*/ */
@ -153,26 +170,37 @@ public:
/** /**
* Pop a cursor palette from the stack, and restore the previous one to * Pop a cursor palette from the stack, and restore the previous one to
* the backend. If there is no previous palette, the cursor palette is * the backend.
* disabled instead. *
* If there is no previous palette, the cursor palette is disabled instead.
*/ */
void popCursorPalette(); void popCursorPalette();
/** /**
* Replace the current cursor palette on the stack. If the stack is * Replace the current cursor palette on the stack.
* empty, the palette is pushed instead. It's a slightly more optimized
* way of popping the old palette before pushing the new one.
* *
* @param colors the new palette data, in interleaved RGB format * If the stack is empty, the palette is pushed instead. This is a slightly
* @param start the first palette entry to be updated * more optimized way of popping the old palette before pushing the new one.
* @param num the number of palette entries to be updated *
* @param colors New palette data, in interleaved RGB format.
* @param start First palette entry to be updated.
* @param num Number of palette entries to be updated.
* *
* @note If num is zero, the cursor palette is disabled. * @note If num is zero, the cursor palette is disabled.
*/ */
void replaceCursorPalette(const byte *colors, uint start, uint num); void replaceCursorPalette(const byte *colors, uint start, uint num);
/**
* Lock or unlock the visibility state of the cursor.
*
* When the cursor is locked, calling showMouse(bool) does nothing
* and returns false.
*/
void lock(bool locked); void lock(bool locked);
private: private:
/**
* Generic class for implementing the singleton design pattern.
*/
friend class Common::Singleton<SingletonBaseType>; friend class Common::Singleton<SingletonBaseType>;
// Even though this is basically the default constructor we implement it // Even though this is basically the default constructor we implement it
// ourselves, so it is private and thus there is no way to create this class // ourselves, so it is private and thus there is no way to create this class
@ -219,7 +247,7 @@ private:
Common::Stack<Palette *> _cursorPaletteStack; Common::Stack<Palette *> _cursorPaletteStack;
bool _locked; bool _locked;
}; };
/** @} */
} // End of namespace Graphics } // End of namespace Graphics
#define CursorMan (::Graphics::CursorManager::instance()) #define CursorMan (::Graphics::CursorManager::instance())

170
graphics/font.h
View File

@ -33,35 +33,50 @@ template<class T> class Array;
namespace Graphics { namespace Graphics {
/**
* @defgroup graphics_font Fonts
* @ingroup graphics
*
* @brief API for representing and managing fonts on the screen.
*
* @{
*/
struct Surface; struct Surface;
class ManagedSurface; class ManagedSurface;
/** Text alignment modes */ /** Text alignment modes. */
enum TextAlign { enum TextAlign {
kTextAlignInvalid, kTextAlignInvalid, ///< Indicates invalid alignment.
kTextAlignStart, ///< Text should be aligned to start of line (virtual) kTextAlignStart, ///< Align the text to start of line (virtual).
kTextAlignLeft, ///< Text should be aligned to the left kTextAlignLeft, ///< Align the text to the left.
kTextAlignCenter, ///< Text should be centered kTextAlignCenter, ///< Center the text.
kTextAlignEnd, ///< Text should be aligned to end of line (virtual) kTextAlignEnd, ///< Align the text to end of line (virtual).
kTextAlignRight ///< Text should be aligned to the right kTextAlignRight ///< Align the text to the right.
}; };
/** Word wrapping modes */ /** Word wrapping modes. */
enum WordWrapMode { enum WordWrapMode {
kWordWrapDefault = 0, kWordWrapDefault = 0, ///< Default wrapping mode.
kWordWrapEvenWidthLines = 1 << 0, ///< Make the resulting line segments close to the same width kWordWrapEvenWidthLines = 1 << 0, ///< Make the resulting line segments close to the same width.
kWordWrapOnExplicitNewLines = 1 << 1 ///< Text is wrapped on new lines, otherwise treats them as single white space. Disables kWordWrapEvenWidthLines kWordWrapOnExplicitNewLines = 1 << 1 ///< Text is wrapped on new lines. Otherwise, treats them as single whitespace. Disables kWordWrapEvenWidthLines.
}; };
/** /**
* Converts virtual text alignments (start + end) * Convert virtual text alignments (start + end)
* to actual text alignment (left + right + center) for drawing, * to actual text alignment (left + right + center) for drawing.
* if given actual text alignments it is returned as-is *
* If actual text alignment is provided, it is returned as-is.
*
* @param alignH The horizontal alignment to convert.
* @param rtl Indicates whether this is an RTL (right-to-left) language (such as Hebrew),
* or a left-to-right language (such as English).
*/ */
TextAlign convertTextAlignH(TextAlign alignH, bool rtl); TextAlign convertTextAlignH(TextAlign alignH, bool rtl);
/** /**
* Instances of this class represent a distinct font, with a built-in renderer. * Instances of this class represent a distinct font, with a built-in renderer.
*
* @todo Maybe move the high-level methods (drawString etc.) to a separate * @todo Maybe move the high-level methods (drawString etc.) to a separate
* FontRenderer class? That way, we could have different variants... ? * FontRenderer class? That way, we could have different variants... ?
*/ */
@ -71,39 +86,42 @@ public:
virtual ~Font() {} virtual ~Font() {}
/** /**
* Query the height of the font. * Return the height of the font.
* *
* @return font height. * @return Font height in pixels.
*/ */
virtual int getFontHeight() const = 0; virtual int getFontHeight() const = 0;
/** /**
* Query the maximum width of the font. * Return the maximum width of the font.
* *
* @return maximum font width. * @return Maximum font width in pixels.
*/ */
virtual int getMaxCharWidth() const = 0; virtual int getMaxCharWidth() const = 0;
/** /**
* Query the width of a specific character. * Return the width of a specific character.
* *
* @param chr The character to query the width of. * @param chr The character to query the width of.
* @return The character's width. *
* @return The width of the character in pixels.
*/ */
virtual int getCharWidth(uint32 chr) const = 0; virtual int getCharWidth(uint32 chr) const = 0;
/** /**
* Query the kerning offset between two characters. * Query the kerning offset between two characters.
* *
* @param left The left character. May be 0. * @param left Left character. Can be 0.
* @param right The right character. May be 0. * @param right Right character. Can be 0.
*
* @return The horizontal displacement. * @return The horizontal displacement.
*/ */
virtual int getKerningOffset(uint32 left, uint32 right) const; virtual int getKerningOffset(uint32 left, uint32 right) const;
/** /**
* Calculate the bounding box of a character. It is assumed that * Calculate the bounding box of a character.
* the character shall be drawn at position (0, 0). *
* It is assumed that the character shall be drawn at position (0, 0).
* *
* The idea here is that the character might be drawn outside the * The idea here is that the character might be drawn outside the
* rect (0, 0) to (getCharWidth(chr), getFontHeight()) for some fonts. * rect (0, 0) to (getCharWidth(chr), getFontHeight()) for some fonts.
@ -112,7 +130,8 @@ public:
* The default implementation simply returns the rect with a width * The default implementation simply returns the rect with a width
* of getCharWidth(chr) and height of getFontHeight(). * of getCharWidth(chr) and height of getFontHeight().
* *
* @param chr The character to draw. * @param chr The character to draw.
*
* @return The bounding box of the drawn glyph. * @return The bounding box of the drawn glyph.
*/ */
virtual Common::Rect getBoundingBox(uint32 chr) const; virtual Common::Rect getBoundingBox(uint32 chr) const;
@ -120,54 +139,75 @@ public:
/** /**
* Return the bounding box of a string drawn with drawString. * Return the bounding box of a string drawn with drawString.
* *
* @param x The x position where to start drawing * @param str The drawn string.
* @param y The y position where to start drawing * @param x The x position where to start drawing.
* @param w The width of the text area. This can be 0 to allow for * @param y The y position where to start drawing.
* obtaining the whole bounding box for a string. Note that this * @param w Width of the text area. This can be 0 to allow for
* does not work with an align different from kTextAlignLeft or * obtaining the whole bounding box for a string. Note that this
* with useEllipsis. * does not work with an align different than kTextAlignLeft or
* @param align The text alignment. This can be used to center a string * with @p useEllipsis.
* in the given area or to align it to the right. * @param align Text alignment. This can be used to center a string
* @param delatx Offset to the x starting position of the string. * in the given area or to align it to the right.
* @param useEllipsis Try to fit the string in the area by inserting an * @param deltax Offset to the x starting position of the string.
* ellipsis. Be ware that the default is false for this * @param useEllipsis Try to fit the string in the area by inserting an
* one unlike for drawString! * ellipsis. Note that the default value is false for this
* argument, unlike for drawString.
*
* @return The actual area where the string is drawn. * @return The actual area where the string is drawn.
*/ */
Common::Rect getBoundingBox(const Common::String &str, int x = 0, int y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const; Common::Rect getBoundingBox(const Common::String &str, int x = 0, int y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const;
/** @overload */
Common::Rect getBoundingBox(const Common::U32String &str, int x = 0, int _y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const; Common::Rect getBoundingBox(const Common::U32String &str, int x = 0, int _y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const;
/** /**
* Draw a character at a specific point on a surface. * Draw a character at a specific point on the surface.
* *
* Note that the point describes the top left edge point where to draw * Note that the point describes the top left edge point where to draw
* the character. This can be different from top left edge point of the * the character. This can be different from the top left edge point of the
* character's bounding box! For example, TTF fonts sometimes move * character's bounding box. For example, TTF fonts sometimes move
* characters like 't' one (or more) pixels to the left to create better * characters like 't' by one (or more) pixels to the left to create better
* visual results. To query the actual bounding box of a character use * visual results. To query the actual bounding box of a character, use
* getBoundingBox. * getBoundingBox.
* @see getBoundingBox * @see getBoundingBox
* *
* The Font implemenation should take care of not drawing outside of the * The Font implementation should take care of not drawing outside of the
* specified surface. * specified surface.
* *
* @param dst The surface to drawn on. * @param dst The surface to draw on.
* @param chr The character to draw. * @param chr The character to draw.
* @param x The x coordinate where to draw the character. * @param x The x coordinate where to draw the character.
* @param y The y coordinate where to draw the character. * @param y The y coordinate where to draw the character.
* @param color The color of the character. * @param color The color of the character.
*/ */
virtual void drawChar(Surface *dst, uint32 chr, int x, int y, uint32 color) const = 0; virtual void drawChar(Surface *dst, uint32 chr, int x, int y, uint32 color) const = 0;
/** @overload */
void drawChar(ManagedSurface *dst, uint32 chr, int x, int y, uint32 color) const; void drawChar(ManagedSurface *dst, uint32 chr, int x, int y, uint32 color) const;
// TODO: Add doxygen comments to this /**
* Draw the given @p str string to the given @p dst surface.
*
* @param dst The surface on which to draw the string.
* @param str The string to draw.
* @param x The x position where to start drawing.
* @param y The y position where to start drawing.
* @param w Width of the text area.
* @param color The color with which to draw the string.
* @param align Text alignment. This can be used to center the string in the given area or to align it to the right.
* @param deltax Offset to the x starting position of the string.
* @param useEllipsis Use ellipsis if needed to fit the string in the area.
*
*/
void drawString(Surface *dst, const Common::String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const; void drawString(Surface *dst, const Common::String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
/** @overload */
void drawString(Surface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const; void drawString(Surface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
/** @overload */
void drawString(ManagedSurface *dst, const Common::String &str, int x, int _y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const; void drawString(ManagedSurface *dst, const Common::String &str, int x, int _y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
/** @overload */
void drawString(ManagedSurface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const; void drawString(ManagedSurface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
/** /**
* Compute and return the width the string str has when rendered using this font. * Compute and return the width of the string @p str when rendered using this font.
*
* This describes the logical width of the string when drawn at (0, 0). * This describes the logical width of the string when drawn at (0, 0).
* This can be different from the actual bounding box of the string. Use * This can be different from the actual bounding box of the string. Use
* getBoundingBox when you need the bounding box of a drawn string. * getBoundingBox when you need the bounding box of a drawn string.
@ -175,28 +215,32 @@ public:
* @see drawChar * @see drawChar
*/ */
int getStringWidth(const Common::String &str) const; int getStringWidth(const Common::String &str) const;
/** @overload */
int getStringWidth(const Common::U32String &str) const; int getStringWidth(const Common::U32String &str) const;
/** /**
* Take a text (which may contain newline characters) and word wrap it so that * Word-wrap a text (that can contain newline characters) so that
* no text line is wider than maxWidth pixels. If necessary, additional line breaks * no text line is wider than @p maxWidth pixels.
* are generated, preferably between words (i.e. where whitespaces are).
* The resulting lines are appended to the lines string list.
* It returns the maximal width of any of the new lines (i.e. a value which is less
* or equal to maxWidth).
* *
* @param str the string to word wrap * If necessary, additional line breaks are generated, preferably between
* @param maxWidth the maximum width a line may have * words, where whitespace is. The resulting lines are appended
* @param lines the string list to which the text lines from str are appended * to the @p lines string list. This returns the maximal width of any of the new
* @param initWidth the starting width of the first line, for partially filled lines (optional) * lines (i.e. a value that is smaller or equal to maxWidth).
* @param mode the wrapping mode. A bitfield of @ref WordWrapMode values *
* @return the maximal width of any of the lines added to lines * @param str The string to word-wrap.
* @param maxWidth Maximum width that a line can have.
* @param lines The string list to which the text lines from @p str are appended.
* @param initWidth Starting width of the first line, for partially filled lines (optional).
* @param mode Wrapping mode. A bitfield of @c WordWrapMode values.
*
* @return The maximal width of any of the lines added to @p lines.
*/ */
int wordWrapText(const Common::String &str, int maxWidth, Common::Array<Common::String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const; int wordWrapText(const Common::String &str, int maxWidth, Common::Array<Common::String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const;
/** @overload */
int wordWrapText(const Common::U32String &str, int maxWidth, Common::Array<Common::U32String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const; int wordWrapText(const Common::U32String &str, int maxWidth, Common::Array<Common::U32String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const;
}; };
/** @} */
} // End of namespace Graphics } // End of namespace Graphics
#endif #endif

347
graphics/managed_surface.h
View File

@ -30,143 +30,164 @@
namespace Graphics { namespace Graphics {
/**
* @defgroup graphics_managed_surface Managed surface
* @ingroup graphics
*
* @brief The ManagedSurface class that adds extra functionality on top of the Surface class.
*
* @{
*/
class Font; class Font;
/** /**
* A derived graphics surface, which handles automatically managing the allocated * A derived graphics surface, which supports automatically managing the allocated
* surface data block, as well as introducing several new blitting methods * surface data block and introduces several new blitting methods.
*/ */
class ManagedSurface { class ManagedSurface {
/** See @ref Font. */
friend class Font; friend class Font;
private: private:
/** /**
* The Graphics::Surface that the managed surface encapsulates * The Graphics::Surface that the managed surface encapsulates.
*/ */
Surface _innerSurface; Surface _innerSurface;
/** /**
* If set, the inner surface will be freed when the surface is recreated, * If set, the inner surface will be freed when the surface is recreated,
* as well as when the surface is destroyed * as well as when the surface is destroyed.
*/ */
DisposeAfterUse::Flag _disposeAfterUse; DisposeAfterUse::Flag _disposeAfterUse;
/** /**
* Stores the owning surface if this If this managed surface represents * If this managed surface represents a subsection of another managed surface,
* a sub-section of another * store the owning surface.
*/ */
ManagedSurface *_owner; ManagedSurface *_owner;
/** /**
* For sub-section areas of an owning parent managed surface, this represents * For a managed surface that has a parent, this represents the offset from
* the offset from the parent's top-left corner this sub-surface starts at * the parent's top-left corner where this sub-surface starts at.
*/ */
Common::Point _offsetFromOwner; Common::Point _offsetFromOwner;
/** /**
* Automatic transparency color. When set, doesn't require transparency to be * Automatic transparency color. When set, it does not require transparency to be
* explicitly passed, and blit methods pass on to transBlit * explicitly passed, and blit methods pass on to transBlit.
*/ */
uint _transparentColor; uint _transparentColor;
bool _transparentColorSet; bool _transparentColorSet;
/** /**
* Local palette for 8-bit images * Local palette for 8-bit images.
*/ */
uint32 _palette[256]; uint32 _palette[256];
bool _paletteSet; bool _paletteSet;
protected: protected:
/** /**
* Base method that descendent classes can override for recording affected * Base method that descendant classes can override for recording the affected
* dirty areas of the surface * dirty areas of the surface.
*/ */
virtual void addDirtyRect(const Common::Rect &r); virtual void addDirtyRect(const Common::Rect &r);
/** /**
* Inner method for blitting * Inner method for blitting.
*/ */
void blitFromInner(const Surface &src, const Common::Rect &srcRect, void blitFromInner(const Surface &src, const Common::Rect &srcRect,
const Common::Point &destPos, const uint32 *palette); const Common::Point &destPos, const uint32 *palette);
/** /**
* Inner method for copying another surface into this one at a given destination position * Inner method for copying another surface into this one at a given destination position.
*/ */
void transBlitFromInner(const Surface &src, const Common::Rect &srcRect, void transBlitFromInner(const Surface &src, const Common::Rect &srcRect,
const Common::Rect &destRect, uint transColor, bool flipped, uint overrideColor, const Common::Rect &destRect, uint transColor, bool flipped, uint overrideColor,
uint srcAlpha, const uint32 *srcPalette, const uint32 *dstPalette, const Surface *mask, bool maskOnly); uint srcAlpha, const uint32 *srcPalette, const uint32 *dstPalette, const Surface *mask, bool maskOnly);
public: public:
/** /**
* Clips the given source bounds so the passed destBounds will be entirely on-screen * Clip the given source bounds so the passed destBounds will be entirely on-screen.
*/ */
bool clip(Common::Rect &srcBounds, Common::Rect &destBounds); bool clip(Common::Rect &srcBounds, Common::Rect &destBounds);
public: public:
uint16 &w; uint16 &w; /*!< Width of the surface rectangle. */
uint16 &h; uint16 &h; /*!< Height of the surface rectangle. */
uint16 &pitch; uint16 &pitch; /*!< Pitch of the surface rectangle. See @ref Surface::pitch. */
PixelFormat &format; PixelFormat &format; /*!< Pixel format of the surface. See @ref PixelFormat. */
public: public:
/** /**
* Create the managed surface * Create the managed surface.
*/ */
ManagedSurface(); ManagedSurface();
/** /**
* Create a managed surface from another one. * Create a managed surface from another one.
* If the source surface is maintaining it's own surface data, then *
* this surface will create it's own surface of the same size and copy * If the source surface is maintaining its own surface data, then
* the contents from the source surface * this surface will create its own surface of the same size and copy
* the contents from the source surface.
*/ */
ManagedSurface(const ManagedSurface &surf); ManagedSurface(const ManagedSurface &surf);
/** /**
* Create the managed surface * Create the managed surface.
*/ */
ManagedSurface(int width, int height); ManagedSurface(int width, int height);
/** /**
* Create the managed surface * Create the managed surface.
*/ */
ManagedSurface(int width, int height, const Graphics::PixelFormat &pixelFormat); ManagedSurface(int width, int height, const Graphics::PixelFormat &pixelFormat);
/** /**
* Create the managed surface * Create the managed surface.
*/ */
ManagedSurface(ManagedSurface &surf, const Common::Rect &bounds); ManagedSurface(ManagedSurface &surf, const Common::Rect &bounds);
/** /**
* Destroy the managed surface * Destroy the managed surface.
*/ */
virtual ~ManagedSurface(); virtual ~ManagedSurface();
/** /**
* Implements automatic conversion to a Graphics::Surface by * Automatically convert to a Graphics::Surface by
* simply returning the inner surface. This must be const, * simply returning the inner surface.
* because we don't want changes being done directly to it, *
* since it would bypass dirty rect handling * This must be const, because changes are not supposed to be done
* directly to it, since it would bypass dirty rect handling.
*/ */
operator const Surface &() const { return _innerSurface; } operator const Surface &() const { return _innerSurface; }
/**
* Automatically convert to a Graphics::Surface by
* simply returning the inner surface.
*
* This must be const, because changes are not supposed to be done
* directly to it, since it would bypass dirty rect handling.
*/
const Surface &rawSurface() const { return _innerSurface; } const Surface &rawSurface() const { return _innerSurface; }
/** /**
* Reassign one managed surface to another one * Reassign one managed surface to another one.
* Note that if the source has a managed surface, it will be duplicated *
* @note If the source has a managed surface, it will be duplicated.
*/ */
ManagedSurface &operator=(const ManagedSurface &surf); ManagedSurface &operator=(const ManagedSurface &surf);
/** /**
* Returns true if the surface has not yet been allocated * Return true if the surface has not yet been allocated.
*/ */
bool empty() const { return w == 0 || h == 0 || _innerSurface.getPixels() == nullptr; } bool empty() const { return w == 0 || h == 0 || _innerSurface.getPixels() == nullptr; }
/** /**
* Returns true if the surface is managing its own pixels * Return true if the surface manages its own pixels.
*/ */
DisposeAfterUse::Flag disposeAfterUse() const { return _disposeAfterUse; } DisposeAfterUse::Flag disposeAfterUse() const { return _disposeAfterUse; }
/** /**
* Return a pointer to the pixel at the specified point. * Return a pointer to the pixel at the specified point.
* *
* @param x The x coordinate of the pixel. * @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel. * @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel. * @return Pointer to the pixel.
*/ */
inline const void *getBasePtr(int x, int y) const { inline const void *getBasePtr(int x, int y) const {
@ -176,8 +197,9 @@ public:
/** /**
* Return a pointer to the pixel at the specified point. * Return a pointer to the pixel at the specified point.
* *
* @param x The x coordinate of the pixel. * @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel. * @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel. * @return Pointer to the pixel.
*/ */
inline void *getBasePtr(int x, int y) { inline void *getBasePtr(int x, int y) {
@ -185,13 +207,14 @@ public:
} }
/** /**
* Get a reference to the pixel data * Get a reference to the pixel data.
*/ */
inline void *getPixels() { return _innerSurface.getPixels(); } inline void *getPixels() { return _innerSurface.getPixels(); }
/** @overload */
inline const void *getPixels() const { return _innerSurface.getPixels(); } inline const void *getPixels() const { return _innerSurface.getPixels(); }
/** /**
* Sets the pixel data. * Set the pixel data.
*/ */
virtual void setPixels(void *newPixels); virtual void setPixels(void *newPixels);
@ -206,240 +229,256 @@ public:
virtual void create(uint16 width, uint16 height, const PixelFormat &pixelFormat); virtual void create(uint16 width, uint16 height, const PixelFormat &pixelFormat);
/** /**
* Sets up the surface as a sub-section of another passed parent surface. This surface * Set up the surface as a subsection of another passed parent surface.
* will not own the pixels, and any dirty rect notifications will automatically be *
* passed to the original parent surface. * This surface will not own the pixels, and any dirty rect notifications will be
* @remarks Note that this differs from Graphics::Surface::getSubArea, in that that * automatically passed to the original parent surface.
* method only adds a single initial dirty rect for the whole area, and then none further *
* @note This differs from Graphics::Surface::getSubArea, in that this
* method only adds a single initial dirty rect for the whole area, and then none more.
*/ */
virtual void create(ManagedSurface &surf, const Common::Rect &bounds); virtual void create(ManagedSurface &surf, const Common::Rect &bounds);
/** /**
* Release the memory used by the pixels memory of this surface. This is the * Release the memory used by the pixel memory of this surface.
* counterpart to create(). *
* This is a counterpart of create().
*/ */
virtual void free(); virtual void free();
/** /**
* Clears any pending dirty rects that have been generated for the surface * Clear any pending dirty rectangles that have been generated for the surface.
*/ */
virtual void clearDirtyRects() {} virtual void clearDirtyRects() {}
/** /**
* When the managed surface is a sub-section of a parent surface, returns the * When the managed surface is a subsection of a parent surface, return the
* the offset in the parent surface that the surface starts at * the offset in the parent surface where the managed surface starts at.
*/ */
const Common::Point getOffsetFromOwner() const { return _offsetFromOwner; } const Common::Point getOffsetFromOwner() const { return _offsetFromOwner; }
/** /**
* Return a rect giving the bounds of the surface * Return a rect providing the bounds of the surface.
*/ */
const Common::Rect getBounds() const { const Common::Rect getBounds() const {
return Common::Rect(0, 0, this->w, this->h); return Common::Rect(0, 0, this->w, this->h);
} }
/** /**
* Copies another surface into this one * Copy another surface into this one.
*/ */
void blitFrom(const Surface &src); void blitFrom(const Surface &src);
/** /**
* Copies another surface into this one at a given destination position * Copy another surface into this one at a given destination position.
*/ */
void blitFrom(const Surface &src, const Common::Point &destPos); void blitFrom(const Surface &src, const Common::Point &destPos);
/** /**
* Copies another surface into this one at a given destination position * Copy another surface into this one at a given destination position.
*/ */
void blitFrom(const Surface &src, const Common::Rect &srcRect, void blitFrom(const Surface &src, const Common::Rect &srcRect,
const Common::Point &destPos); const Common::Point &destPos);
/** /**
* Copies another surface into this one * Copy another surface into this one.
*/ */
void blitFrom(const ManagedSurface &src); void blitFrom(const ManagedSurface &src);
/** /**
* Copies another surface into this one at a given destination position * Copy another surface into this one at a given destination position.
*/ */
void blitFrom(const ManagedSurface &src, const Common::Point &destPos); void blitFrom(const ManagedSurface &src, const Common::Point &destPos);
/** /**
* Copies another surface into this one at a given destination position * Copy another surface into this one at a given destination position.
*/ */
void blitFrom(const ManagedSurface &src, const Common::Rect &srcRect, void blitFrom(const ManagedSurface &src, const Common::Rect &srcRect,
const Common::Point &destPos); const Common::Point &destPos);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param transColor Transparency color to ignore copying * @param src Source surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const Surface &src, uint transColor = 0, bool flipped = false, void transBlitFrom(const Surface &src, uint transColor = 0, bool flipped = false,
uint overrideColor = 0, uint srcAlpha = 0xff); uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param destPos Destination position to draw the surface * @param src Source surface.
* @param transColor Transparency color to ignore copying * @param destPos Destination position to draw the surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const Surface &src, const Common::Point &destPos, void transBlitFrom(const Surface &src, const Common::Point &destPos,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff); uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param destPos Destination position to draw the surface * @param src Source surface.
* @param mask Mask definition * @param destPos Destination position to draw the surface.
* @param mask Mask definition.
*/ */
void transBlitFrom(const Surface &src, const Common::Point &destPos, void transBlitFrom(const Surface &src, const Common::Point &destPos,
const ManagedSurface &mask); const ManagedSurface &mask);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param destPos Destination position to draw the surface * @param src Source surface.
* @param mask Mask definition * @param destPos Destination position to draw the surface.
* @param mask Mask definition.
*/ */
void transBlitFrom(const Surface &src, const Common::Point &destPos, void transBlitFrom(const Surface &src, const Common::Point &destPos,
const Surface &mask); const Surface &mask);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param srcRect Sub-section of source surface to draw * @param src Source surface.
* @param destPos Destination position to draw the surface * @param srcRect Subsection of the source surface to draw.
* @param transColor Transparency color to ignore copying * @param destPos Destination position to draw the surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Specifies whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Point &destPos, void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Point &destPos,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff); uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param srcRect Sub-section of source surface to draw * @param src Source surface.
* @param srcRect Subsection of the source surface to draw.
* @param destRect Destination area to draw the surface in. This can be sized differently * @param destRect Destination area to draw the surface in. This can be sized differently
* then srcRect, allowing for arbitrary scaling of the image * then @p srcRect, allowing for arbitrary scaling of the image.
* @param transColor Transparency color to ignore copying * @param transColor Transparency color to ignore copying of.
* @param flipped Specifies whether to horizontally flip the image * @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
* @param mask Optional parameter with mask definition * @param mask Optional parameter with mask definition.
* @param maskOnly Optional parameter for using mask over transColor * @param maskOnly Optional parameter for using mask over @p transColor.
*/ */
void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Rect &destRect, void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Rect &destRect,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff, uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff,
const Surface *mask = nullptr, bool maskOnly = false); const Surface *mask = nullptr, bool maskOnly = false);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param transColor Transparency color to ignore copying * @param src Source surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const ManagedSurface &src, uint transColor = 0, bool flipped = false, void transBlitFrom(const ManagedSurface &src, uint transColor = 0, bool flipped = false,
uint overrideColor = 0, uint srcAlpha = 0xff); uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param destPos Destination position to draw the surface * @param src Source surface.
* @param transColor Transparency color to ignore copying * @param destPos Destination position to draw the surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos, void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff); uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param destPos Destination position to draw the surface * @param src Source surface.
* @param mask Mask definition * @param destPos Destination position to draw the surface.
* @param mask Mask definition.
*/ */
void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos, void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos,
const ManagedSurface &mask); const ManagedSurface &mask);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param srcRect Sub-section of source surface to draw * @param src Source surface.
* @param destPos Destination position to draw the surface * @param srcRect Subsection of the source surface to draw.
* @param transColor Transparency color to ignore copying * @param destPos Destination position to draw the surface.
* @param flipped Specifies whether to horizontally flip the image * @param transColor Transparency color to ignore copying of.
* @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
*/ */
void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Point &destPos, void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Point &destPos,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff); uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
/** /**
* Copies another surface into this one ignoring pixels of a designated transparent color * Copy another surface into this one, ignoring pixels of a designated transparent color.
* @param src Source surface *
* @param srcRect Sub-section of source surface to draw * @param src Source surface.
* @param srcRect Subsection of the source surface to draw.
* @param destRect Destination area to draw the surface in. This can be sized differently * @param destRect Destination area to draw the surface in. This can be sized differently
* then srcRect, allowing for arbitrary scaling of the image * then @p srcRect, allowing for arbitrary scaling of the image.
* @param transColor Transparency color to ignore copying * @param transColor Transparency color to ignore copying of.
* @param flipped Specifies whether to horizontally flip the image * @param flipped Whether to horizontally flip the image.
* @param overrideColor Optional color to use instead of non-transparent pixels from * @param overrideColor Optional color to use instead of non-transparent pixels from
* the source surface * the source surface.
* @param srcAlpha Optional additional transparency applied to src * @param srcAlpha Optional additional transparency applied to @p src.
* @param mask Optional parameter with mask definition * @param mask Optional parameter with mask definition.
* @param maskOnly Optional parameter for using mask over transColor * @param maskOnly Optional parameter for using mask over @p transColor.
*/ */
void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Rect &destRect, void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Rect &destRect,
uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff, uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff,
const Surface *mask = nullptr, bool maskOnly = false); const Surface *mask = nullptr, bool maskOnly = false);
/** /**
* Clear the entire surface * Clear the entire surface.
*/ */
void clear(uint color = 0); void clear(uint color = 0);
/** /**
* Mark the entire surface as dirty * Mark the entire surface as dirty.
*/ */
void markAllDirty(); void markAllDirty();
/** /**
* Copies a bitmap to the Surface internal buffer. The pixel format * Copy a bitmap to the internal buffer of the surface.
* of buffer must match the pixel format of the Surface. *
* The pixel format of the buffer must match the pixel format of the surface.
*/ */
void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height) { void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height) {
_innerSurface.copyRectToSurface(buffer, srcPitch, destX, destY, width, height); _innerSurface.copyRectToSurface(buffer, srcPitch, destX, destY, width, height);
} }
/** /**
* Copies a bitmap to the Surface internal buffer. The pixel format * Copy a bitmap to the internal buffer of the surface.
* of buffer must match the pixel format of the Surface. *
* The pixel format of the buffer must match the pixel format of the surface.
*/ */
void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect) { void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect) {
_innerSurface.copyRectToSurface(srcSurface, destX, destY, subRect); _innerSurface.copyRectToSurface(srcSurface, destX, destY, subRect);
} }
/** /**
* Copy the data from another Surface, reinitializing the * Copy the data from another surface, reinitializing the
* surface to match the dimensions of the passed surface * surface to match the dimensions of the passed surface.
*/ */
void copyFrom(const ManagedSurface &surf); void copyFrom(const ManagedSurface &surf);
@ -492,7 +531,7 @@ public:
} }
/** /**
* Returns a sub-area of the screen, but only adds a single initial dirty rect * Return a sub-area of the screen, but only add a single initial dirty rect
* for the retrieved area. * for the retrieved area.
*/ */
Surface getSubArea(const Common::Rect &area) { Surface getSubArea(const Common::Rect &area) {
@ -503,24 +542,24 @@ public:
/** /**
* Convert the data to another pixel format. * Convert the data to another pixel format.
* *
* This works in-place. This means it will not create an additional buffer * This works in-place. This means it does not create an additional buffer
* for the conversion process. The value of 'pixels' might change though * for the conversion process. The value of 'pixels' might change though
* (that means it might realloc the pixel data). * (that means it might realloc the pixel data).
* *
* @param dstFormat The desired format * @param dstFormat The desired format.
* @param palette The palette (in RGB888), if the source format has a Bpp of 1 * @param palette The palette (in RGB888), if the source format has a bpp of 1.
*/ */
void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0) { void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0) {
_innerSurface.convertToInPlace(dstFormat, palette); _innerSurface.convertToInPlace(dstFormat, palette);
} }
/** /**
* Returns the current transparent color * Return the current transparent color.
*/ */
uint getTransparentColor() const { return _transparentColor; } uint getTransparentColor() const { return _transparentColor; }
/** /**
* Sets the transparent color * Set the transparent color.
*/ */
void setTransparentColor(uint color) { void setTransparentColor(uint color) {
_transparentColor = color; _transparentColor = color;
@ -528,44 +567,44 @@ public:
} }
/** /**
* Clears the transparent color setting * Clear the transparent color setting.
*/ */
void clearTransparentColor() { void clearTransparentColor() {
_transparentColorSet = false; _transparentColorSet = false;
} }
/** /**
* Returns true if a transparent color has been set * Return true if a transparent color has been set.
*/ */
bool hasTransparentColor() const { bool hasTransparentColor() const {
return _transparentColorSet; return _transparentColorSet;
} }
/** /**
* Clear any existing palette * Clear any existing palette.
*/ */
void clearPalette() { void clearPalette() {
_paletteSet = false; _paletteSet = false;
} }
/** /**
* Gets the palette array * Get the palette array.
*/ */
const uint32 *getPalette() const { const uint32 *getPalette() const {
return _palette; return _palette;
} }
/** /**
* Sets the palette using RGB tuplets * Set the palette using RGB tuples.
*/ */
void setPalette(const byte *colors, uint start, uint num); void setPalette(const byte *colors, uint start, uint num);
/** /**
* Sets the palette using RGBA values * Set the palette using RGBA values.
*/ */
void setPalette(const uint32 *colors, uint start, uint num); void setPalette(const uint32 *colors, uint start, uint num);
}; };
/** @} */
} // End of namespace Graphics } // End of namespace Graphics
#endif #endif

117
graphics/pixelformat.h
View File

@ -28,18 +28,27 @@
namespace Graphics { namespace Graphics {
/** Template to expand from an n-bit component to an 8-bit component */ /**
* @defgroup graphics_pixelformat Pixel formats
* @ingroup graphics
*
* @brief Structures for managing pixel formats.
*
* @{
*/
/** Template to expand from an n-bit component to an 8-bit component. */
template<int depth> template<int depth>
struct ColorComponent { struct ColorComponent {
}; };
/** Return 0 for an empty color component. */
template<> template<>
struct ColorComponent<0> { struct ColorComponent<0> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
return 0; return 0;
} }
}; };
/** Template to expand a 1-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<1> { struct ColorComponent<1> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -54,7 +63,7 @@ struct ColorComponent<1> {
(value << 7); (value << 7);
} }
}; };
/** Template to expand a 2-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<2> { struct ColorComponent<2> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -65,7 +74,7 @@ struct ColorComponent<2> {
(value << 6); (value << 6);
} }
}; };
/** Template to expand a 3-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<3> { struct ColorComponent<3> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -75,7 +84,7 @@ struct ColorComponent<3> {
(value >> 1); (value >> 1);
} }
}; };
/** Template to expand a 4-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<4> { struct ColorComponent<4> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -84,7 +93,7 @@ struct ColorComponent<4> {
(value << 4); (value << 4);
} }
}; };
/** Template to expand a 5-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<5> { struct ColorComponent<5> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -93,7 +102,7 @@ struct ColorComponent<5> {
(value >> 2); (value >> 2);
} }
}; };
/** Template to expand a 6-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<6> { struct ColorComponent<6> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -102,7 +111,7 @@ struct ColorComponent<6> {
(value >> 4); (value >> 4);
} }
}; };
/** Template to expand a 7-bit component into an 8-bit component. */
template<> template<>
struct ColorComponent<7> { struct ColorComponent<7> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -111,7 +120,7 @@ struct ColorComponent<7> {
(value >> 6); (value >> 6);
} }
}; };
/** Return the given value. */
template<> template<>
struct ColorComponent<8> { struct ColorComponent<8> {
static inline uint expand(uint value) { static inline uint expand(uint value) {
@ -120,17 +129,17 @@ struct ColorComponent<8> {
}; };
/** /**
* A pixel format description. * Pixel format description.
* *
* Like ColorMasks it includes the given values to create colors from RGB * Like ColorMasks, it includes the given values to create colors from RGB
* values and to retrieve RGB values from colors. * values and to retrieve RGB values from colors.
* *
* Unlike ColorMasks it is not dependend on knowing the exact pixel format * Unlike ColorMasks, it is not dependent on knowing the exact pixel format
* on compile time. * on compile time.
* *
* A minor difference between ColorMasks and PixelFormat is that ColorMasks * A minor difference between ColorMasks and PixelFormat is that ColorMasks
* stores the bit count per channel in 'kFooBits', while PixelFormat stores * stores the bit count per channel in @c kFooBits, while PixelFormat stores
* the loss compared to 8 bits per channel in '#Loss'. It also doesn't * the loss compared to 8 bits per channel in @c \#Loss. It also does not
* contain mask values. * contain mask values.
*/ */
struct PixelFormat { struct PixelFormat {
@ -139,12 +148,31 @@ struct PixelFormat {
byte rLoss, gLoss, bLoss, aLoss; /**< Precision loss of each color component. */ byte rLoss, gLoss, bLoss, aLoss; /**< Precision loss of each color component. */
byte rShift, gShift, bShift, aShift; /**< Binary left shift of each color component in the pixel value. */ byte rShift, gShift, bShift, aShift; /**< Binary left shift of each color component in the pixel value. */
/** Default constructor that creates a null pixel format. */
inline PixelFormat() { inline PixelFormat() {
bytesPerPixel = bytesPerPixel =
rLoss = gLoss = bLoss = aLoss = rLoss = gLoss = bLoss = aLoss =
rShift = gShift = bShift = aShift = 0; rShift = gShift = bShift = aShift = 0;
} }
/** Construct a pixel format based on the provided arguments.
*
* Examples:
*
* - RGBA8888:
* @code
* BytesPerPixel = 4, RBits = GBits = BBits = ABits = 8, RShift = 24, GShift = 16, BShift = 8, AShift = 0
* @endcode
* - ABGR8888:
* @code
* BytesPerPixel = 4, RBits = GBits = BBits = ABits = 8, RShift = 0, GShift = 8, BShift = 16, AShift = 24
* @endcode
* - RGB565:
* @code
* BytesPerPixel = 2, RBits = 5, GBits = 6, BBits = 5, ABits = 0, RShift = 11, GShift = 5, BShift = 0, AShift = 0
* @endcode
*/
inline PixelFormat(byte BytesPerPixel, inline PixelFormat(byte BytesPerPixel,
byte RBits, byte GBits, byte BBits, byte ABits, byte RBits, byte GBits, byte BBits, byte ABits,
byte RShift, byte GShift, byte BShift, byte AShift) { byte RShift, byte GShift, byte BShift, byte AShift) {
@ -159,10 +187,12 @@ struct PixelFormat {
aShift = AShift; aShift = AShift;
} }
/** Define a CLUT8 pixel format. */
static inline PixelFormat createFormatCLUT8() { static inline PixelFormat createFormatCLUT8() {
return PixelFormat(1, 0, 0, 0, 0, 0, 0, 0, 0); return PixelFormat(1, 0, 0, 0, 0, 0, 0, 0, 0);
} }
/** Check if two pixel formats are the same */
inline bool operator==(const PixelFormat &fmt) const { inline bool operator==(const PixelFormat &fmt) const {
// TODO: If aLoss==8, then the value of aShift is irrelevant, and should be ignored. // TODO: If aLoss==8, then the value of aShift is irrelevant, and should be ignored.
return bytesPerPixel == fmt.bytesPerPixel && return bytesPerPixel == fmt.bytesPerPixel &&
@ -176,10 +206,12 @@ struct PixelFormat {
aShift == fmt.aShift; aShift == fmt.aShift;
} }
/** Check if two pixel formats are different. */
inline bool operator!=(const PixelFormat &fmt) const { inline bool operator!=(const PixelFormat &fmt) const {
return !(*this == fmt); return !(*this == fmt);
} }
/** Return an RGB color value from red, green, and blue values. */
inline uint32 RGBToColor(uint8 r, uint8 g, uint8 b) const { inline uint32 RGBToColor(uint8 r, uint8 g, uint8 b) const {
return return
((0xFF >> aLoss) << aShift) | ((0xFF >> aLoss) << aShift) |
@ -188,6 +220,7 @@ struct PixelFormat {
(( b >> bLoss) << bShift); (( b >> bLoss) << bShift);
} }
/** Return an ARGB color value from alpha, red, green, and blue values. */
inline uint32 ARGBToColor(uint8 a, uint8 r, uint8 g, uint8 b) const { inline uint32 ARGBToColor(uint8 a, uint8 r, uint8 g, uint8 b) const {
return return
((a >> aLoss) << aShift) | ((a >> aLoss) << aShift) |
@ -196,12 +229,14 @@ struct PixelFormat {
((b >> bLoss) << bShift); ((b >> bLoss) << bShift);
} }
/** Retrieve red, green, and blue values from an RGB color value. */
inline void colorToRGB(uint32 color, uint8 &r, uint8 &g, uint8 &b) const { inline void colorToRGB(uint32 color, uint8 &r, uint8 &g, uint8 &b) const {
r = expand(rBits(), color >> rShift); r = expand(rBits(), color >> rShift);
g = expand(gBits(), color >> gShift); g = expand(gBits(), color >> gShift);
b = expand(bBits(), color >> bShift); b = expand(bBits(), color >> bShift);
} }
/** Retrieve alpha, red, green, and blue values from an ARGB color value. */
inline void colorToARGB(uint32 color, uint8 &a, uint8 &r, uint8 &g, uint8 &b) const { inline void colorToARGB(uint32 color, uint8 &a, uint8 &r, uint8 &g, uint8 &b) const {
a = (aBits() == 0) ? 0xFF : expand(aBits(), color >> aShift); a = (aBits() == 0) ? 0xFF : expand(aBits(), color >> aShift);
r = expand(rBits(), color >> rShift); r = expand(rBits(), color >> rShift);
@ -209,51 +244,81 @@ struct PixelFormat {
b = expand(bBits(), color >> bShift); b = expand(bBits(), color >> bShift);
} }
////////////////////////////////////////////////////////////////////// /**
// Convenience functions for getting number of color component bits // * @name Convenience functions for getting the number of color component bits
////////////////////////////////////////////////////////////////////// * @{
*/
/**
* Return the number of red component bits.
*/
inline byte rBits() const { inline byte rBits() const {
return (8 - rLoss); return (8 - rLoss);
} }
/**
* Return the number of green component bits.
*/
inline byte gBits() const { inline byte gBits() const {
return (8 - gLoss); return (8 - gLoss);
} }
/**
* Return the number of blue component bits.
*/
inline byte bBits() const { inline byte bBits() const {
return (8 - bLoss); return (8 - bLoss);
} }
/**
* Return the number of alpha component bits.
*/
inline byte aBits() const { inline byte aBits() const {
return (8 - aLoss); return (8 - aLoss);
} }
/**
* Return the total number of bits for the pixel format.
*/
inline byte bpp() const { inline byte bpp() const {
return rBits() + gBits() + bBits() + aBits(); return rBits() + gBits() + bBits() + aBits();
} }
/** @} */
/**
* @name Convenience functions for getting color components' maximum values
* @{
*/
//////////////////////////////////////////////////////////////////////// /**
// Convenience functions for getting color components' maximum values // * Return the maximum value of red.
//////////////////////////////////////////////////////////////////////// */
inline uint rMax() const { inline uint rMax() const {
return (1 << rBits()) - 1; return (1 << rBits()) - 1;
} }
/**
* Return the maximum value of green.
*/
inline uint gMax() const { inline uint gMax() const {
return (1 << gBits()) - 1; return (1 << gBits()) - 1;
} }
/**
* Return the maximum value of blue.
*/
inline uint bMax() const { inline uint bMax() const {
return (1 << bBits()) - 1; return (1 << bBits()) - 1;
} }
/**
* Return the maximum value of alpha.
*/
inline uint aMax() const { inline uint aMax() const {
return (1 << aBits()) - 1; return (1 << aBits()) - 1;
} }
/** @} */
/** Expand a given bit-depth component to a full 8-bit component */ /** Expand a given bit-depth component to a full 8-bit component. @todo is that different from the templates at the beginning? */
static inline uint expand(uint bits, uint color) { static inline uint expand(uint bits, uint color) {
switch (bits) { switch (bits) {
case 0: case 0:
@ -281,10 +346,10 @@ struct PixelFormat {
// Unsupported // Unsupported
return 0; return 0;
} }
/** Return string representation. */
Common::String toString() const; Common::String toString() const;
}; };
/** @} */
} // End of namespace Graphics } // End of namespace Graphics
#endif #endif

278
graphics/surface.h
View File

@ -36,43 +36,52 @@ struct Point;
namespace Graphics { namespace Graphics {
/** /**
* An arbitrary graphics surface, which can be the target (or source) of blit * @defgroup graphics_surface Surface
* @ingroup graphics
*
* @brief Surface class for managing an arbitrary graphics surface.
*
* @{
*/
/**
* An arbitrary graphics surface that can be the target (or source) of blit
* operations, font rendering, etc. * operations, font rendering, etc.
*/ */
struct Surface { struct Surface {
/* /*
* IMPORTANT implementation specific detail: * IMPORTANT implementation-specific detail:
* *
* ARM code relies on the layout of the first 3 of these fields. Do not * ARM code relies on the layout of the first 3 of these fields. Do not
* change them. * change them.
*/ */
/** /**
* The width of the surface. * Width of the surface.
*/ */
uint16 w; uint16 w;
/** /**
* The height of the surface. * Height of the surface.
*/ */
uint16 h; uint16 h;
/** /**
* The number of bytes a pixel line has. * Number of bytes in a pixel line.
* *
* Note that this might not equal w * bytesPerPixel. * @note This might not equal w * bytesPerPixel.
*/ */
uint16 pitch; uint16 pitch;
protected: protected:
/** /**
* The surface's pixel data. * Pixel data of the surface.
*/ */
void *pixels; void *pixels;
public: public:
/** /**
* The pixel format of the surface. * Pixel format of the surface.
*/ */
PixelFormat format; PixelFormat format;
@ -101,9 +110,9 @@ public:
} }
/** /**
* Sets the pixel data. * Set the pixel data.
* *
* Note that this is a simply a setter. Be careful what you are doing! * Note that this is a simply a setter. Be aware of that when using it.
* *
* @param newPixels The new pixel data. * @param newPixels The new pixel data.
*/ */
@ -112,8 +121,9 @@ public:
/** /**
* Return a pointer to the pixel at the specified point. * Return a pointer to the pixel at the specified point.
* *
* @param x The x coordinate of the pixel. * @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel. * @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel. * @return Pointer to the pixel.
*/ */
inline const void *getBasePtr(int x, int y) const { inline const void *getBasePtr(int x, int y) const {
@ -123,8 +133,9 @@ public:
/** /**
* Return a pointer to the pixel at the specified point. * Return a pointer to the pixel at the specified point.
* *
* @param x The x coordinate of the pixel. * @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel. * @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel. * @return Pointer to the pixel.
*/ */
inline void *getBasePtr(int x, int y) { inline void *getBasePtr(int x, int y) {
@ -134,223 +145,232 @@ public:
/** /**
* Allocate memory for the pixel data of the surface. * Allocate memory for the pixel data of the surface.
* *
* Note that you are responsible for calling free yourself. * The client code is responsible for calling @ref free.
* @see free
* *
* @param width Width of the surface object. * @param width Width of the surface object.
* @param height Height of the surface object. * @param height Height of the surface object.
* @param format The pixel format the surface should use. * @param format The pixel format to be used by the surface.
*/ */
void create(uint16 width, uint16 height, const PixelFormat &format); void create(uint16 width, uint16 height, const PixelFormat &format);
/** /**
* Release the memory used by the pixels memory of this surface. This is the * Release the memory used by the pixel memory of this surface.
* counterpart to create().
* *
* Note that you should only use this, when you created the Surface data via * This is the counterpart of @ref create().
* create! Otherwise this function has undefined behavior. *
* @see create * @b Important: Only use this if you created the surface data using
* @ref create. Otherwise, this function has undefined behavior.
*/ */
void free(); void free();
/** /**
* Set up the Surface with user specified data. * Set up a surface with user-specified data.
* *
* Note that this simply sets the 'internal' attributes of the Surface. It * This simply sets the 'internal' attributes of the surface. It
* will not take care of freeing old data via free or similar! * does free old data using @ref free or similar methods.
* *
* @param width Width of the pixel data. * @param width Width of the pixel data.
* @param height Height of the pixel data. * @param height Height of the pixel data.
* @param pitch The pitch of the pixel data. * @param pitch Pitch of the pixel data.
* @param pixels The pixel data itself. * @param pixels Pixel data.
* @param format The pixel format of the pixel data. * @param format Pixel format of the pixel data.
*/ */
void init(uint16 width, uint16 height, uint16 pitch, void *pixels, const PixelFormat &format); void init(uint16 width, uint16 height, uint16 pitch, void *pixels, const PixelFormat &format);
/** /**
* Copy the data from another Surface. * Copy the data from another surface.
* *
* Note that this calls free on the current surface, to assure it being * This calls @ref free on the current surface to assure that it is
* clean. So be sure the current data was created via create, otherwise * clean. Make sure that the current data was created using @ref create.
* the results are undefined. * Otherwise, the results are undefined.
* @see create
* @see free
* *
* @param surf Surface to copy from. * @param surf The surface to copy from.
*/ */
void copyFrom(const Surface &surf); void copyFrom(const Surface &surf);
/** /**
* Creates a Surface which represents a sub-area of this Surface object. * Create a surface that represents a sub-area of this Surface object.
* *
* The pixel (0, 0) of the returned Surface will be the same as Pixel * The pixel (0, 0) of the returned Surface will be the same as pixel
* (area.x, area.y) of this Surface. Changes to any of the Surface objects * (area.x, area.y) of the parent surface. Changes to any of the parent surface
* will change the shared pixel data. * objects will change the shared pixel data.
* *
* Note that the Surface returned is only valid as long as this Surface * The returned surface is only valid as long as this Surface
* object is still alive (i.e. its pixel data is not destroyed or * object still exists, that is, its pixel data is not destroyed or
* reallocated). Do *never* try to free the returned Surface. * reallocated.
* *
* @param area The area which should be represented. Note that the area * @b Important: Never attempt to free the returned surface.
* will get clipped in case it does not fit! *
* @param area The area to be represented. Note that the area
* will get clipped in case it does not fit.
*/ */
Surface getSubArea(const Common::Rect &area); Surface getSubArea(const Common::Rect &area);
/** /**
* Creates a Surface which represents a sub-area of this Surface object. * Create a surface that represents a sub-area of this Surface object.
* *
* The pixel (0, 0) of the returned Surface will be the same as Pixel * The pixel (0, 0) of the returned surface will be the same as pixel
* (area.x, area.y) of this Surface. * (area.x, area.y) of the parent surface.
* *
* Note that the Surface returned is only valid as long as this Surface * The returned surface is only valid as long as this Surface
* object is still alive (i.e. its pixel data is not destroyed or * object still exists, that is, its pixel data is not destroyed or
* reallocated). Do *never* try to free the returned Surface. * reallocated.
* *
* @param area The area which should be represented. Note that the area * @b Important: Never attempt to free the returned surface.
* will get clipped in case it does not fit! *
* @param area The area to be represented. Note that the area
* will get clipped in case it does not fit.
*/ */
const Surface getSubArea(const Common::Rect &area) const; const Surface getSubArea(const Common::Rect &area) const;
/** /**
* Copies a bitmap to the Surface internal buffer. The pixel format * Copy a bitmap to the internal buffer of the surface.
* of buffer must match the pixel format of the Surface.
* *
* @param buffer The buffer containing the graphics data source * The pixel format of the buffer must match the pixel format of the surface.
* @param srcPitch The pitch of the buffer (number of bytes in a scanline) *
* @param destX The x coordinate of the destination rectangle * @param buffer Buffer containing the graphics data source.
* @param destY The y coordinate of the destination rectangle * @param srcPitch Pitch of the buffer (number of bytes in a scanline).
* @param width The width of the destination rectangle * @param destX The x coordinate of the destination rectangle.
* @param height The height of the destination rectangle * @param destY The y coordinate of the destination rectangle.
* @param width Width of the destination rectangle.
* @param height Height of the destination rectangle.
*/ */
void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height); void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height);
/** /**
* Copies a bitmap to the Surface internal buffer. The pixel format * Copy a bitmap to the internal buffer of the surface.
* of buffer must match the pixel format of the Surface.
* *
* @param srcSurface The source of the bitmap data * The pixel format of the buffer must match the pixel format of the surface.
* @param destX The x coordinate of the destination rectangle *
* @param destY The y coordinate of the destination rectangle * @param srcSurface Source of the bitmap data.
* @param subRect The subRect of surface to be blitted * @param destX The x coordinate of the destination rectangle.
* @param destY The y coordinate of the destination rectangle.
* @param subRect The subRect of the surface to be blitted.
*/ */
void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect); void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect);
/** /**
* Convert the data to another pixel format. * Convert the data to another pixel format.
* *
* This works in-place. This means it will not create an additional buffer * This works in-place. This means it does not create an additional buffer
* for the conversion process. The value of 'pixels' might change though * for the conversion process. The value of 'pixels' might change though
* (that means it might realloc the pixel data). * (that means it might realloc the pixel data).
* *
* Note that you should only use this, when you created the Surface data via * @b Important: Only use this if you created the surface data using
* create! Otherwise this function has undefined behavior. * @ref create. Otherwise, this function has undefined behavior.
* *
* @param dstFormat The desired format * @param dstFormat The desired format.
* @param palette The palette (in RGB888), if the source format has a Bpp of 1 * @param palette The palette (in RGB888), if the source format has a bpp of 1.
*/ */
void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0); void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0);
/** /**
* Convert the data to another pixel format. * Convert the data to another pixel format.
* *
* The calling code must call free on the returned surface and then delete * The client code must call @ref free on the returned surface and then delete
* it. * it.
* *
* @param dstFormat The desired format * @param dstFormat The desired format.
* @param palette The palette (in RGB888), if the source format has a Bpp of 1 * @param palette The palette (in RGB888), if the source format has a bpp of 1.
*/ */
Graphics::Surface *convertTo(const PixelFormat &dstFormat, const byte *palette = 0) const; Graphics::Surface *convertTo(const PixelFormat &dstFormat, const byte *palette = 0) const;
/** /**
* Draw a line. * Draw a line.
* *
* @param x0 The x coordinate of the start point. * @param x0 The x coordinate of the start point.
* @param y0 The y coordiante of the start point. * @param y0 The y coordinate of the start point.
* @param x1 The x coordinate of the end point. * @param x1 The x coordinate of the end point.
* @param y1 The y coordinate of the end point. * @param y1 The y coordinate of the end point.
* @param color The color of the line. * @param color Color of the line.
* @note This is just a wrapper around Graphics::drawLine *
* @note This is just a wrapper around Graphics::drawLine.
*/ */
void drawLine(int x0, int y0, int x1, int y1, uint32 color); void drawLine(int x0, int y0, int x1, int y1, uint32 color);
/** /**
* Draw a thick line. * Draw a thick line.
* *
* @param x0 The x coordinate of the start point. * @param x0 The x coordinate of the start point.
* @param y0 The y coordiante of the start point. * @param y0 The y coordinate of the start point.
* @param x1 The x coordinate of the end point. * @param x1 The x coordinate of the end point.
* @param y1 The y coordinate of the end point. * @param y1 The y coordinate of the end point.
* @param penX The width of the pen (thickness in the x direction) * @param penX Width of the pen (thickness in the x direction).
* @param penY The height of the pen (thickness in the y direction) * @param penY Height of the pen (thickness in the y direction).
* @param color The color of the line. * @param color Color of the line.
* @note This is just a wrapper around Graphics::drawThickLine *
* @note The x/y coordinates of the start and end points are the upper-left most part of the pen * @note This is just a wrapper around Graphics::drawThickLine.
*
* @note The x/y coordinates of the start and end points are the upper leftmost part of the pen.
*/ */
void drawThickLine(int x0, int y0, int x1, int y1, int penX, int penY, uint32 color); void drawThickLine(int x0, int y0, int x1, int y1, int penX, int penY, uint32 color);
/** /**
* Draw a horizontal line. * Draw a horizontal line.
* *
* @param x The start x coordinate of the line. * @param x The start x coordinate of the line.
* @param y The y coordiante of the line. * @param y The y coordinate of the line.
* @param x2 The end x coordinate of the line. * @param x2 The end x coordinate of the line.
* In case x > x2 the coordinates are swapped. * In case x > x2, the coordinates are swapped.
* @param color The color of the line. * @param color Color of the line.
*/ */
void hLine(int x, int y, int x2, uint32 color); void hLine(int x, int y, int x2, uint32 color);
/** /**
* Draw a vertical line. * Draw a vertical line.
* *
* @param x The x coordinate of the line. * @param x The x coordinate of the line.
* @param y The start y coordiante of the line. * @param y The start y coordinate of the line.
* @param y2 The end y coordinate of the line. * @param y2 The end y coordinate of the line.
* In case y > y2 the coordinates are swapped. * In case y > y2, the coordinates are swapped.
* @param color The color of the line. * @param color Color of the line.
*/ */
void vLine(int x, int y, int y2, uint32 color); void vLine(int x, int y, int y2, uint32 color);
/** /**
* Fill a rect with a given color. * Fill a rect with a given color.
* *
* @param r Rect to fill * @param r The rectangle to fill.
* @param color The color of the rect's contents. * @param color The color to fill the rect with.
*/ */
void fillRect(Common::Rect r, uint32 color); void fillRect(Common::Rect r, uint32 color);
/** /**
* Draw a frame around a specified rect. * Draw a frame around a specified rect.
* *
* @param r Rect to frame * @param r The rectangle to frame.
* @param color The color of the frame. * @param color The color of the frame.
*/ */
void frameRect(const Common::Rect &r, uint32 color); void frameRect(const Common::Rect &r, uint32 color);
// See comment in graphics/surface.cpp about it /**
* Move the content of the surface horizontally or vertically
* by the given number of pixels.
*/
void move(int dx, int dy, int height); void move(int dx, int dy, int height);
/** /**
* Flip the specified rect vertically. * Flip the specified rect vertically.
* *
* @param r Rect to flip * @param r The rectangle to flip.
*/ */
void flipVertical(const Common::Rect &r); void flipVertical(const Common::Rect &r);
/** /**
* Scale the data to the given size. * Scale the data to the given size.
* *
* The calling code must call free on the returned surface and then delete * The client code must call @ref free on the returned surface and then delete
* it. * it.
* *
* @param newWidth the resulting width. * @param newWidth The resulting width.
* @param newHeight the resulting height. * @param newHeight The resulting height.
* @param filtering Whether or not to use bilinear filtering. * @param filtering Whether or not to use bilinear filtering.
*/ */
Graphics::Surface *scale(uint16 newWidth, uint16 newHeight, bool filtering = false) const; Graphics::Surface *scale(uint16 newWidth, uint16 newHeight, bool filtering = false) const;
}; };
/** /**
* A deleter for Surface objects which can be used with SharedPtr. * A deleter for Surface objects that can be used with SharedPtr.
* *
* This deleter assures Surface::free is called on deletion. * This deleter assures Surface::free is called on deletion.
*/ */
@ -364,23 +384,23 @@ struct SurfaceDeleter {
}; };
/** /**
* Stack-based flood fill algorithm for arbitrary Surfaces. * Stack-based flood fill algorithm for arbitrary surfaces.
* *
* It could be used in 2 ways. One is to fill the pixels of oldColor * This can be used in two ways. One is to fill the pixels of oldColor
* with fillColor. Second is when the surface stays intact but another * with fillColor. Second is when the surface stays intact but another
* surface with mask is created, where filled colors are marked with 255. * surface with mask is created, where filled colors are marked with 255.
* *
* Before running fill() or fillMask(), the initial pixels must be addSeed * Before running fill() or fillMask(), the initial pixels must be addSeed
* with addSeed() method. * with the addSeed() method.
*/ */
class FloodFill { class FloodFill {
public: public:
/** /**
* Construct a simple Surface object. * Construct a simple Surface object.
* *
* @param surface Input surface * @param surface Input surface.
* @param oldColor Color on the surface to change * @param oldColor The color on the surface to change.
* @param fillColor Color to fill with * @param fillColor The color to fill with.
*/ */
FloodFill(Surface *surface, uint32 oldColor, uint32 fillColor, bool maskMode = false); FloodFill(Surface *surface, uint32 oldColor, uint32 fillColor, bool maskMode = false);
~FloodFill(); ~FloodFill();
@ -388,27 +408,25 @@ public:
/** /**
* Add pixels to the fill queue. * Add pixels to the fill queue.
* *
* @param x The x coordinate of the pixel. * @param x The x coordinate of the pixel.
* @param y The x coordinate of the pixel. * @param y The x coordinate of the pixel.
*/ */
void addSeed(int x, int y); void addSeed(int x, int y);
/** /**
* Fill the surface as requested. * Fill the surface as requested.
* *
* It uses pixels which were added with addSeed() method. * This uses pixels that were added with the @ref addSeed() method.
*
* @see addSeed
*/ */
void fill(); void fill();
/** /**
* Fill the mask. The mask is a CLUT8 Surface with pixels 0 and 255. * Fill the mask.
*
* The mask is a CLUT8 surface with pixels 0 and 255.
* 255 means that the pixel has been filled. * 255 means that the pixel has been filled.
* *
* It uses pixels which were added with addSeed() method. * This uses pixels that were added with the @ref addSeed() method.
*
* @see addSeed
*/ */
void fillMask(); void fillMask();
@ -429,7 +447,7 @@ private:
bool _maskMode; bool _maskMode;
}; };
/** @} */
} // End of namespace Graphics } // End of namespace Graphics