libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2025-02-21 03:31:40 +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
@brief API of various image decoders used in engines.

138
graphics/cursorman.h
View File

@ -31,19 +31,28 @@
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> {
public:
/** Query whether the mouse cursor is visible. */
/** Return whether the mouse cursor is visible. */
bool isVisible();
/**
* Show or hide the mouse cursor.
*
* 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
* not call OSystem::updateScreen itself after a showMouse(true) call.
* You may need to call OSystem::updateScreen after a call to showMouse(true)
* 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
* hand OSystem::updateScreen might as well display unwanted changes on
* the screen. Another alternative would be to let the backend worry
@ -54,22 +63,24 @@ public:
bool showMouse(bool visible);
/**
* Push a new cursor onto the stack, and set it in the backend. A local
* copy will be made of the cursor data, so the original buffer can be
* safely freed afterwards.
* Push a new cursor onto the stack, and set it in the backend.
*
* @param buf the new cursor data
* @param w the width
* @param h the height
* @param hotspotX the hotspot X coordinate
* @param hotspotY the hotspot Y coordinate
* @param keycolor the color value for the transparent color. This may not exceed
* A local copy of the cursor data will be made, so the original buffer
* can be safely freed afterwards.
*
* @param buf New cursor data.
* @param w Width.
* @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.
* @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.
* @param format a pointer to the pixel format which the cursor graphic uses,
* 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
* @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.
* @param format Pointer to the pixel format that the cursor graphic uses.
* CLUT8 will be used if this is null or not specified.
*
* @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
* 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
* backend. If there is no previous cursor, the cursor is hidden.
* backend.
*
* If there is no previous cursor, the cursor is hidden.
*/
void popCursor();
/**
* Replace the current cursor on the stack. If the stack is empty, the
* cursor is pushed instead. It's a slightly more optimized way of
* popping the old cursor before pushing the new one.
* Replace the current cursor on the stack.
*
* @param buf the new cursor data
* @param w the width
* @param h the height
* @param hotspotX the hotspot X coordinate
* @param hotspotY the hotspot Y coordinate
* @param keycolor the color value for the transparent color. This may not exceed
* 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 buf New cursor data.
* @param w Width.
* @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.
* @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.
* @param format a pointer to the pixel format which the cursor graphic uses,
* CLUT8 will be used if this is NULL or not specified.
* @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.
* @param format Pointer to the pixel format that the cursor graphic uses,
* 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);
/**
* Replace the current cursor on the stack. If the stack is empty, the
* cursor is pushed instead. It's a slightly more optimized way of
* popping the old cursor before pushing the new one.
* Replace the current cursor on the stack.
*
* @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);
/**
* Pop all of the cursors and cursor palettes from their respective stacks.
* The purpose is to ensure that all unecessary cursors are removed from the
* Pop all cursors and cursor palettes from their respective stacks.
*
* The purpose is to ensure that all unnecessary cursors are removed from the
* stack when returning to the launcher from an engine.
*
*/
@ -120,8 +136,8 @@ public:
/**
* Test whether cursor palettes are supported.
*
* This is just an convenience wrapper for checking for
* OSystem::kFeatureCursorPalette to be supported by OSystem.
* This is just an convenience wrapper for checking whether
* OSystem::kFeatureCursorPalette is supported by OSystem.
*
* @see OSystem::kFeatureCursorPalette
* @see OSystem::hasFeature
@ -129,7 +145,7 @@ public:
bool supportsCursorPalettes();
/**
* Enable/Disable the current cursor palette.
* Enable or disable the current cursor palette.
*
* @param disable
*/
@ -137,15 +153,16 @@ public:
/**
* 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
* used by all backends.
*
* @param colors the new palette data, in interleaved RGB format
* @param start the first palette entry to be updated
* @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.
*/
@ -153,26 +170,37 @@ public:
/**
* 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
* disabled instead.
* the backend.
*
* If there is no previous palette, the cursor palette is disabled instead.
*/
void popCursorPalette();
/**
* Replace the current cursor palette on the stack. If the stack is
* empty, the palette is pushed instead. It's a slightly more optimized
* way of popping the old palette before pushing the new one.
* Replace the current cursor palette on the stack.
*
* @param colors the new palette data, in interleaved RGB format
* @param start the first palette entry to be updated
* @param num the number of palette entries to be updated
* If the stack is empty, the palette is pushed instead. This is a slightly
* more optimized way of popping the old palette before pushing the new one.
*
* @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.
*/
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);
private:
/**
* Generic class for implementing the singleton design pattern.
*/
friend class Common::Singleton<SingletonBaseType>;
// 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
@ -219,7 +247,7 @@ private:
Common::Stack<Palette *> _cursorPaletteStack;
bool _locked;
};
/** @} */
} // End of namespace Graphics
#define CursorMan (::Graphics::CursorManager::instance())

170
graphics/font.h
View File

@ -33,35 +33,50 @@ template<class T> class Array;
namespace Graphics {
/**
* @defgroup graphics_font Fonts
* @ingroup graphics
*
* @brief API for representing and managing fonts on the screen.
*
* @{
*/
struct Surface;
class ManagedSurface;
/** Text alignment modes */
/** Text alignment modes. */
enum TextAlign {
kTextAlignInvalid,
kTextAlignStart, ///< Text should be aligned to start of line (virtual)
kTextAlignLeft, ///< Text should be aligned to the left
kTextAlignCenter, ///< Text should be centered
kTextAlignEnd, ///< Text should be aligned to end of line (virtual)
kTextAlignRight ///< Text should be aligned to the right
kTextAlignInvalid, ///< Indicates invalid alignment.
kTextAlignStart, ///< Align the text to start of line (virtual).
kTextAlignLeft, ///< Align the text to the left.
kTextAlignCenter, ///< Center the text.
kTextAlignEnd, ///< Align the text to end of line (virtual).
kTextAlignRight ///< Align the text to the right.
};
/** Word wrapping modes */
/** Word wrapping modes. */
enum WordWrapMode {
kWordWrapDefault = 0,
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
kWordWrapDefault = 0, ///< Default wrapping mode.
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 whitespace. Disables kWordWrapEvenWidthLines.
};
/**
* Converts virtual text alignments (start + end)
* to actual text alignment (left + right + center) for drawing,
* if given actual text alignments it is returned as-is
* Convert virtual text alignments (start + end)
* to actual text alignment (left + right + center) for drawing.
*
* 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);
/**
* 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
* FontRenderer class? That way, we could have different variants... ?
*/
@ -71,39 +86,42 @@ public:
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;
/**
* 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;
/**
* Query the width of a specific character.
* Return the width of a specific character.
*
* @param chr The character to query the width of.
* @return The character's width.
* @param chr The character to query the width of.
*
* @return The width of the character in pixels.
*/
virtual int getCharWidth(uint32 chr) const = 0;
/**
* Query the kerning offset between two characters.
*
* @param left The left character. May be 0.
* @param right The right character. May be 0.
* @param left Left character. Can be 0.
* @param right Right character. Can be 0.
*
* @return The horizontal displacement.
*/
virtual int getKerningOffset(uint32 left, uint32 right) const;
/**
* Calculate the bounding box of a character. It is assumed that
* the character shall be drawn at position (0, 0).
* Calculate the bounding box of a character.
*
* 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
* 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
* 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.
*/
virtual Common::Rect getBoundingBox(uint32 chr) const;
@ -120,54 +139,75 @@ public:
/**
* Return the bounding box of a string drawn with drawString.
*
* @param x The x position where to start drawing
* @param y The y position where to start drawing
* @param w The width of the text area. This can be 0 to allow for
* obtaining the whole bounding box for a string. Note that this
* does not work with an align different from kTextAlignLeft or
* with useEllipsis.
* @param align The text alignment. This can be used to center a string
* in the given area or to align it to the right.
* @param delatx Offset to the x starting position of the string.
* @param useEllipsis Try to fit the string in the area by inserting an
* ellipsis. Be ware that the default is false for this
* one unlike for drawString!
* @param str The drawn string.
* @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. This can be 0 to allow for
* obtaining the whole bounding box for a string. Note that this
* does not work with an align different than kTextAlignLeft or
* with @p useEllipsis.
* @param align Text alignment. This can be used to center a 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 Try to fit the string in the area by inserting an
* ellipsis. Note that the default value is false for this
* argument, unlike for drawString.
*
* @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;
/** @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;
/**
* 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
* the character. This can be different from top left edge point of the
* character's bounding box! For example, TTF fonts sometimes move
* characters like 't' one (or more) pixels to the left to create better
* visual results. To query the actual bounding box of a character use
* the character. This can be different from the top left edge point of the
* character's bounding box. For example, TTF fonts sometimes move
* 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
* 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.
*
* @param dst The surface to drawn on.
* @param chr The character to draw.
* @param x The x coordinate where to draw the character.
* @param y The y coordinate where to draw the character.
* @param dst The surface to draw on.
* @param chr The character to draw.
* @param x The x coordinate where to draw the character.
* @param y The y coordinate where to draw the character.
* @param color The color of the character.
*/
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;
// 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;
/** @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;
/** @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;
/** @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;
/**
* 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 can be different from the actual bounding box of the string. Use
* getBoundingBox when you need the bounding box of a drawn string.
@ -175,28 +215,32 @@ public:
* @see drawChar
*/
int getStringWidth(const Common::String &str) const;
/** @overload */
int getStringWidth(const Common::U32String &str) const;
/**
* Take a text (which may contain newline characters) and word wrap it so that
* no text line is wider than maxWidth pixels. If necessary, additional line breaks
* 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).
* Word-wrap a text (that can contain newline characters) so that
* no text line is wider than @p maxWidth pixels.
*
* @param str the string to word wrap
* @param maxWidth the maximum width a line may have
* @param lines the string list to which the text lines from str are appended
* @param initWidth the starting width of the first line, for partially filled lines (optional)
* @param mode the wrapping mode. A bitfield of @ref WordWrapMode values
* @return the maximal width of any of the lines added to lines
* If necessary, additional line breaks are generated, preferably between
* words, where whitespace is. The resulting lines are appended
* to the @p lines string list. This returns the maximal width of any of the new
* lines (i.e. a value that is smaller or equal to maxWidth).
*
* @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;
/** @overload */
int wordWrapText(const Common::U32String &str, int maxWidth, Common::Array<Common::U32String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const;
};
/** @} */
} // End of namespace Graphics
#endif

347
graphics/managed_surface.h
View File

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

117
graphics/pixelformat.h
View File

@ -28,18 +28,27 @@
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>
struct ColorComponent {
};
/** Return 0 for an empty color component. */
template<>
struct ColorComponent<0> {
static inline uint expand(uint value) {
return 0;
}
};
/** Template to expand a 1-bit component into an 8-bit component. */
template<>
struct ColorComponent<1> {
static inline uint expand(uint value) {
@ -54,7 +63,7 @@ struct ColorComponent<1> {
(value << 7);
}
};
/** Template to expand a 2-bit component into an 8-bit component. */
template<>
struct ColorComponent<2> {
static inline uint expand(uint value) {
@ -65,7 +74,7 @@ struct ColorComponent<2> {
(value << 6);
}
};
/** Template to expand a 3-bit component into an 8-bit component. */
template<>
struct ColorComponent<3> {
static inline uint expand(uint value) {
@ -75,7 +84,7 @@ struct ColorComponent<3> {
(value >> 1);
}
};
/** Template to expand a 4-bit component into an 8-bit component. */
template<>
struct ColorComponent<4> {
static inline uint expand(uint value) {
@ -84,7 +93,7 @@ struct ColorComponent<4> {
(value << 4);
}
};
/** Template to expand a 5-bit component into an 8-bit component. */
template<>
struct ColorComponent<5> {
static inline uint expand(uint value) {
@ -93,7 +102,7 @@ struct ColorComponent<5> {
(value >> 2);
}
};
/** Template to expand a 6-bit component into an 8-bit component. */
template<>
struct ColorComponent<6> {
static inline uint expand(uint value) {
@ -102,7 +111,7 @@ struct ColorComponent<6> {
(value >> 4);
}
};
/** Template to expand a 7-bit component into an 8-bit component. */
template<>
struct ColorComponent<7> {
static inline uint expand(uint value) {
@ -111,7 +120,7 @@ struct ColorComponent<7> {
(value >> 6);
}
};
/** Return the given value. */
template<>
struct ColorComponent<8> {
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.
*
* 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.
*
* A minor difference between ColorMasks and PixelFormat is that ColorMasks
* stores the bit count per channel in 'kFooBits', while PixelFormat stores
* the loss compared to 8 bits per channel in '#Loss'. It also doesn't
* stores the bit count per channel in @c kFooBits, while PixelFormat stores
* the loss compared to 8 bits per channel in @c \#Loss. It also does not
* contain mask values.
*/
struct PixelFormat {
@ -139,12 +148,31 @@ struct PixelFormat {
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. */
/** Default constructor that creates a null pixel format. */
inline PixelFormat() {
bytesPerPixel =
rLoss = gLoss = bLoss = aLoss =
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,
byte RBits, byte GBits, byte BBits, byte ABits,
byte RShift, byte GShift, byte BShift, byte AShift) {
@ -159,10 +187,12 @@ struct PixelFormat {
aShift = AShift;
}
/** Define a CLUT8 pixel format. */
static inline PixelFormat createFormatCLUT8() {
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 {
// TODO: If aLoss==8, then the value of aShift is irrelevant, and should be ignored.
return bytesPerPixel == fmt.bytesPerPixel &&
@ -176,10 +206,12 @@ struct PixelFormat {
aShift == fmt.aShift;
}
/** Check if two pixel formats are different. */
inline bool operator!=(const PixelFormat &fmt) const {
return !(*this == fmt);
}
/** Return an RGB color value from red, green, and blue values. */
inline uint32 RGBToColor(uint8 r, uint8 g, uint8 b) const {
return
((0xFF >> aLoss) << aShift) |
@ -188,6 +220,7 @@ struct PixelFormat {
(( 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 {
return
((a >> aLoss) << aShift) |
@ -196,12 +229,14 @@ struct PixelFormat {
((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 {
r = expand(rBits(), color >> rShift);
g = expand(gBits(), color >> gShift);
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 {
a = (aBits() == 0) ? 0xFF : expand(aBits(), color >> aShift);
r = expand(rBits(), color >> rShift);
@ -209,51 +244,81 @@ struct PixelFormat {
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 {
return (8 - rLoss);
}
/**
* Return the number of green component bits.
*/
inline byte gBits() const {
return (8 - gLoss);
}
/**
* Return the number of blue component bits.
*/
inline byte bBits() const {
return (8 - bLoss);
}
/**
* Return the number of alpha component bits.
*/
inline byte aBits() const {
return (8 - aLoss);
}
/**
* Return the total number of bits for the pixel format.
*/
inline byte bpp() const {
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 {
return (1 << rBits()) - 1;
}
/**
* Return the maximum value of green.
*/
inline uint gMax() const {
return (1 << gBits()) - 1;
}
/**
* Return the maximum value of blue.
*/
inline uint bMax() const {
return (1 << bBits()) - 1;
}
/**
* Return the maximum value of alpha.
*/
inline uint aMax() const {
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) {
switch (bits) {
case 0:
@ -281,10 +346,10 @@ struct PixelFormat {
// Unsupported
return 0;
}
/** Return string representation. */
Common::String toString() const;
};
/** @} */
} // End of namespace Graphics
#endif

278
graphics/surface.h
View File

@ -36,43 +36,52 @@ struct Point;
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.
*/
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
* change them.
*/
/**
* The width of the surface.
* Width of the surface.
*/
uint16 w;
/**
* The height of the surface.
* Height of the surface.
*/
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;
protected:
/**
* The surface's pixel data.
* Pixel data of the surface.
*/
void *pixels;
public:
/**
* The pixel format of the surface.
* Pixel format of the surface.
*/
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.
*/
@ -112,8 +121,9 @@ public:
/**
* Return a pointer to the pixel at the specified point.
*
* @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel.
* @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel.
*/
inline const void *getBasePtr(int x, int y) const {
@ -123,8 +133,9 @@ public:
/**
* Return a pointer to the pixel at the specified point.
*
* @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel.
* @param x The x coordinate of the pixel.
* @param y The y coordinate of the pixel.
*
* @return Pointer to the pixel.
*/
inline void *getBasePtr(int x, int y) {
@ -134,223 +145,232 @@ public:
/**
* Allocate memory for the pixel data of the surface.
*
* Note that you are responsible for calling free yourself.
* @see free
* The client code is responsible for calling @ref free.
*
* @param width Width of the surface object.
* @param height Height of the surface object.
* @param format The pixel format the surface should use.
* @param width Width of the surface object.
* @param height Height of the surface object.
* @param format The pixel format to be used by the surface.
*/
void create(uint16 width, uint16 height, const PixelFormat &format);
/**
* Release the memory used by the pixels memory of this surface. This is the
* counterpart to create().
* Release the memory used by the pixel memory of this surface.
*
* Note that you should only use this, when you created the Surface data via
* create! Otherwise this function has undefined behavior.
* @see create
* This is the counterpart of @ref create().
*
* @b Important: Only use this if you created the surface data using
* @ref create. Otherwise, this function has undefined behavior.
*/
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
* will not take care of freeing old data via free or similar!
* This simply sets the 'internal' attributes of the surface. It
* does free old data using @ref free or similar methods.
*
* @param width Width of the pixel data.
* @param height Height of the pixel data.
* @param pitch The pitch of the pixel data.
* @param pixels The pixel data itself.
* @param format The pixel format of the pixel data.
* @param width Width of the pixel data.
* @param height Height of the pixel data.
* @param pitch Pitch of the pixel data.
* @param pixels Pixel data.
* @param format Pixel format of the pixel data.
*/
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
* clean. So be sure the current data was created via create, otherwise
* the results are undefined.
* @see create
* @see free
* This calls @ref free on the current surface to assure that it is
* clean. Make sure that the current data was created using @ref create.
* Otherwise, the results are undefined.
*
* @param surf Surface to copy from.
* @param surf The surface to copy from.
*/
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
* (area.x, area.y) of this Surface. Changes to any of the Surface objects
* will change the shared pixel data.
* The pixel (0, 0) of the returned Surface will be the same as pixel
* (area.x, area.y) of the parent surface. Changes to any of the parent surface
* objects will change the shared pixel data.
*
* Note that the Surface returned is only valid as long as this Surface
* object is still alive (i.e. its pixel data is not destroyed or
* reallocated). Do *never* try to free the returned Surface.
* The returned surface is only valid as long as this Surface
* object still exists, that is, its pixel data is not destroyed or
* reallocated.
*
* @param area The area which should be represented. Note that the area
* will get clipped in case it does not fit!
* @b Important: Never attempt to free the returned surface.
*
* @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);
/**
* 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
* (area.x, area.y) of this Surface.
* The pixel (0, 0) of the returned surface will be the same as pixel
* (area.x, area.y) of the parent surface.
*
* Note that the Surface returned is only valid as long as this Surface
* object is still alive (i.e. its pixel data is not destroyed or
* reallocated). Do *never* try to free the returned Surface.
* The returned surface is only valid as long as this Surface
* object still exists, that is, its pixel data is not destroyed or
* reallocated.
*
* @param area The area which should be represented. Note that the area
* will get clipped in case it does not fit!
* @b Important: Never attempt to free the returned surface.
*
* @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;
/**
* Copies a bitmap to the Surface internal buffer. The pixel format
* of buffer must match the pixel format of the Surface.
* Copy a bitmap to the internal buffer of the surface.
*
* @param buffer The buffer containing the graphics data source
* @param srcPitch The pitch of the buffer (number of bytes in a scanline)
* @param destX The x coordinate of the destination rectangle
* @param destY The y coordinate of the destination rectangle
* @param width The width of the destination rectangle
* @param height The height of the destination rectangle
* The pixel format of the buffer must match the pixel format of the surface.
*
* @param buffer Buffer containing the graphics data source.
* @param srcPitch Pitch of the buffer (number of bytes in a scanline).
* @param destX The x coordinate 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);
/**
* Copies a bitmap to the Surface internal buffer. The pixel format
* of buffer must match the pixel format of the Surface.
* Copy a bitmap to the internal buffer of the surface.
*
* @param srcSurface The source of the bitmap data
* @param destX The x coordinate of the destination rectangle
* @param destY The y coordinate of the destination rectangle
* @param subRect The subRect of surface to be blitted
* The pixel format of the buffer must match the pixel format of the surface.
*
* @param srcSurface Source of the bitmap data.
* @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);
/**
* 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
* (that means it might realloc the pixel data).
*
* Note that you should only use this, when you created the Surface data via
* create! Otherwise this function has undefined behavior.
* @b Important: Only use this if you created the surface data using
* @ref create. Otherwise, this function has undefined behavior.
*
* @param dstFormat The desired format
* @param palette The palette (in RGB888), if the source format has a Bpp of 1
* @param dstFormat The desired format.
* @param palette The palette (in RGB888), if the source format has a bpp of 1.
*/
void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0);
/**
* 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.
*
* @param dstFormat The desired format
* @param palette The palette (in RGB888), if the source format has a Bpp of 1
* @param dstFormat The desired format.
* @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;
/**
* Draw a line.
*
* @param x0 The x coordinate of the start point.
* @param y0 The y coordiante of the start point.
* @param x1 The x coordinate of the end point.
* @param y1 The y coordinate of the end point.
* @param color The color of the line.
* @note This is just a wrapper around Graphics::drawLine
* @param x0 The x coordinate of the start point.
* @param y0 The y coordinate of the start point.
* @param x1 The x coordinate of the end point.
* @param y1 The y coordinate of the end point.
* @param color Color of the line.
*
* @note This is just a wrapper around Graphics::drawLine.
*/
void drawLine(int x0, int y0, int x1, int y1, uint32 color);
/**
* Draw a thick line.
*
* @param x0 The x coordinate of the start point.
* @param y0 The y coordiante of the start point.
* @param x1 The x 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 penY The height of the pen (thickness in the y direction)
* @param color The 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
* @param x0 The x coordinate of the start point.
* @param y0 The y coordinate of the start point.
* @param x1 The x coordinate of the end point.
* @param y1 The y coordinate of the end point.
* @param penX Width of the pen (thickness in the x direction).
* @param penY Height of the pen (thickness in the y direction).
* @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 leftmost part of the pen.
*/
void drawThickLine(int x0, int y0, int x1, int y1, int penX, int penY, uint32 color);
/**
* Draw a horizontal line.
*
* @param x The start x coordinate of the line.
* @param y The y coordiante of the line.
* @param x2 The end x coordinate of the line.
* In case x > x2 the coordinates are swapped.
* @param color The color of the line.
* @param x The start x coordinate of the line.
* @param y The y coordinate of the line.
* @param x2 The end x coordinate of the line.
* In case x > x2, the coordinates are swapped.
* @param color Color of the line.
*/
void hLine(int x, int y, int x2, uint32 color);
/**
* Draw a vertical line.
*
* @param x The x coordinate of the line.
* @param y The start y coordiante of the line.
* @param y2 The end y coordinate of the line.
* In case y > y2 the coordinates are swapped.
* @param color The color of the line.
* @param x The x coordinate of the line.
* @param y The start y coordinate of the line.
* @param y2 The end y coordinate of the line.
* In case y > y2, the coordinates are swapped.
* @param color Color of the line.
*/
void vLine(int x, int y, int y2, uint32 color);
/**
* Fill a rect with a given color.
*
* @param r Rect to fill
* @param color The color of the rect's contents.
* @param r The rectangle to fill.
* @param color The color to fill the rect with.
*/
void fillRect(Common::Rect r, uint32 color);
/**
* Draw a frame around a specified rect.
*
* @param r Rect to frame
* @param color The color of the frame.
* @param r The rectangle to frame.
* @param color The color of the frame.
*/
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);
/**
* Flip the specified rect vertically.
*
* @param r Rect to flip
* @param r The rectangle to flip.
*/
void flipVertical(const Common::Rect &r);
/**
* 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.
*
* @param newWidth the resulting width.
* @param newHeight the resulting height.
* @param filtering Whether or not to use bilinear filtering.
* @param newWidth The resulting width.
* @param newHeight The resulting height.
* @param filtering Whether or not to use bilinear filtering.
*/
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.
*/
@ -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
* surface with mask is created, where filled colors are marked with 255.
*
* Before running fill() or fillMask(), the initial pixels must be addSeed
* with addSeed() method.
* with the addSeed() method.
*/
class FloodFill {
public:
/**
* Construct a simple Surface object.
*
* @param surface Input surface
* @param oldColor Color on the surface to change
* @param fillColor Color to fill with
* @param surface Input surface.
* @param oldColor The color on the surface to change.
* @param fillColor The color to fill with.
*/
FloodFill(Surface *surface, uint32 oldColor, uint32 fillColor, bool maskMode = false);
~FloodFill();
@ -388,27 +408,25 @@ public:
/**
* Add pixels to the fill queue.
*
* @param x The x coordinate of the pixel.
* @param y The x coordinate of the pixel.
* @param x The x coordinate of the pixel.
* @param y The x coordinate of the pixel.
*/
void addSeed(int x, int y);
/**
* Fill the surface as requested.
*
* It uses pixels which were added with addSeed() method.
*
* @see addSeed
* This uses pixels that were added with the @ref addSeed() method.
*/
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.
*
* It uses pixels which were added with addSeed() method.
*
* @see addSeed
* This uses pixels that were added with the @ref addSeed() method.
*/
void fillMask();
@ -429,7 +447,7 @@ private:
bool _maskMode;
};
/** @} */
} // End of namespace Graphics