From 22e09bedaaf125365c6905187db80e939a86df53 Mon Sep 17 00:00:00 2001 From: Jody Northup Date: Mon, 6 Jul 2009 07:40:28 +0000 Subject: Updated doxygen comments on API functions svn-id: r42166 --- common/system.h | 14 ++++++++++---- engines/engine.h | 2 ++ graphics/conversion.h | 9 ++++++--- graphics/cursorman.h | 11 ++++++----- graphics/pixelformat.h | 14 +++++++++++++- 5 files changed, 37 insertions(+), 13 deletions(-) diff --git a/common/system.h b/common/system.h index 6f3dc6b6c8..b37797811a 100644 --- a/common/system.h +++ b/common/system.h @@ -376,8 +376,10 @@ public: * * @see Graphics::PixelFormat * - * @note All backends supporting RGB color must be able to accept game data - * in RGB color order, even if hardware uses BGR or some other color order. + * @note Backends supporting RGB color should accept game data in RGB color + * order, even if hardware uses BGR or some other color order. + * + * @see convertScreenRect */ virtual Common::List getSupportedFormats() const = 0; #else @@ -412,7 +414,7 @@ public: * This is the pixel format for which the client code generates data; * this is not necessarily equal to the hardware pixel format. For example, * a backend may perform color lookup of 8-bit graphics before pushing - * a screen to hardware, or correct the ARGB color order. + * a screen to hardware, or correct the ARGB color order via convertScreenRect. * * @param width the new virtual screen width * @param height the new virtual screen height @@ -1026,6 +1028,8 @@ public: private: /** * Convert a rectangle from the screen format to the hardware format. + * Expected usage is for this to be called in copyRectToScreen when + * conversion is necessary. * * @param dstbuf the buffer which will recieve the converted graphics data * @param srcbuf the buffer containing the original graphics data @@ -1040,7 +1044,9 @@ private: * @note This implementation is slow. Please override this if * your backend hardware has a better way to deal with this. * @note This implementation requires the screen pixel format and - * the hardware pixel format to have a matching bytedepth + * the hardware pixel format to have a matching bytedepth. + * @note This is meant for RGB modes only, do not attempt + * to use it when running in 256 color mode. */ virtual bool convertScreenRect(byte *dstbuf, const byte *srcbuf, int dstpitch, int srcpitch, int w, int h, Graphics::PixelFormat hwFmt) { diff --git a/engines/engine.h b/engines/engine.h index c643d5895f..d570f18073 100644 --- a/engines/engine.h +++ b/engines/engine.h @@ -59,6 +59,8 @@ void initCommonGFX(bool defaultTo1XScaler); * * Errors out when backend is not able to switch to the specified * mode. + * + * Defaults to 256 color paletted mode if no graphics format is provided. */ void initGraphics(int width, int height, bool defaultTo1xScaler, const Graphics::PixelFormat *format = NULL); diff --git a/graphics/conversion.h b/graphics/conversion.h index 3226c38817..b0314046b9 100644 --- a/graphics/conversion.h +++ b/graphics/conversion.h @@ -48,7 +48,7 @@ inline static void RGB2YUV(byte r, byte g, byte b, byte &y, byte &u, byte &v) { // TODO: generic YUV to RGB blit /** - * Convert a rectangle from the one format to another, and blits it. + * Blits a rectangle from one graphical format to another. * * @param dstbuf the buffer which will recieve the converted graphics data * @param srcbuf the buffer containing the original graphics data @@ -61,8 +61,11 @@ inline static void RGB2YUV(byte r, byte g, byte b, byte &y, byte &u, byte &v) { * @return true if conversion completes successfully, * false if there is an error. * - * @note This implementation currently requires the destination's - * format have at least as high a bitdepth as the source's. + * @note This implementation currently arbitrarily requires that the + * destination's format have at least as high a bytedepth as + * the source's. + * @note This can convert a rectangle in place, if the source and + * destination format have the same bytedepth. * */ bool crossBlit(byte *dst, const byte *src, int dstpitch, int srcpitch, diff --git a/graphics/cursorman.h b/graphics/cursorman.h index ba11c9ef96..ae7008f54c 100644 --- a/graphics/cursorman.h +++ b/graphics/cursorman.h @@ -63,14 +63,14 @@ public: * safely freed afterwards. * * @param buf the new cursor data - * @param w the width - * @param h the height + * @param w the width + * @param h the height * @param hotspotX the hotspot X coordinate * @param hotspotY the hotspot Y coordinate * @param keycolor the index for the transparent color * @param targetScale the scale for which the cursor is designed - * @param format the pixel format which the cursor graphic uses - * + * @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 * useful to push a "dummy" cursor and modify it later. The * cursor will be added to the stack, but not to the backend. @@ -95,7 +95,8 @@ public: * @param hotspotY the hotspot Y coordinate * @param keycolor the index for the transparent color * @param targetScale the scale for which the cursor is designed - * @param format the pixel format which the cursor graphic uses + * @param format a pointer to the pixel format which the cursor graphic uses, + * CLUT8 will be used if this is NULL or not specified. */ void replaceCursor(const byte *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor = 0xFFFFFFFF, int targetScale = 1, const Graphics::PixelFormat *format = NULL); diff --git a/graphics/pixelformat.h b/graphics/pixelformat.h index a1883291b9..bf18197f25 100644 --- a/graphics/pixelformat.h +++ b/graphics/pixelformat.h @@ -65,7 +65,11 @@ struct PixelFormat { rShift = RShift, gShift = GShift, bShift = BShift, aShift = AShift; } - // "Factory" methods for convenience + ///////////////////////////////////////////////////////// + // Convenience functions for creating standard formats // + ///////////////////////////////////////////////////////// + + // 256 color palette. static inline PixelFormat createFormatCLUT8() { return PixelFormat(1, 8, 8, 8, 8, 0, 0, 0, 0); } @@ -201,6 +205,14 @@ struct PixelFormat { } }; +/** + * Determines the first matching format between two lists. + * + * @param backend The higher priority list, meant to be a list of formats supported by the backend + * @param frontend The lower priority list, meant to be a list of formats supported by the engine + * @return The first item on the backend list that also occurs on the frontend list + * or PixelFormat::createFormatCLUT8() if no matching formats were found. + */ inline PixelFormat findCompatibleFormat(Common::List backend, Common::List frontend) { #ifdef ENABLE_RGB_COLOR for (Common::List::iterator i = backend.begin(); i != backend.end(); ++i) { -- cgit v1.2.3