[Scummvm-cvs-logs] SF.net SVN: scummvm:[41785] scummvm/trunk/engines/sci/gfx
fingolfin at users.sourceforge.net
fingolfin at users.sourceforge.net
Mon Jun 22 23:48:48 CEST 2009
Revision: 41785
http://scummvm.svn.sourceforge.net/scummvm/?rev=41785&view=rev
Author: fingolfin
Date: 2009-06-22 21:48:47 +0000 (Mon, 22 Jun 2009)
Log Message:
-----------
Patch #2810483 (SCI: Convert gfx subsystem headers to Doxygen format), with @brief removed
Modified Paths:
--------------
scummvm/trunk/engines/sci/gfx/font.h
scummvm/trunk/engines/sci/gfx/gfx_driver.h
scummvm/trunk/engines/sci/gfx/gfx_gui.h
scummvm/trunk/engines/sci/gfx/gfx_options.h
scummvm/trunk/engines/sci/gfx/gfx_res_options.h
scummvm/trunk/engines/sci/gfx/gfx_resmgr.h
scummvm/trunk/engines/sci/gfx/gfx_resource.h
scummvm/trunk/engines/sci/gfx/gfx_state_internal.h
scummvm/trunk/engines/sci/gfx/gfx_system.h
scummvm/trunk/engines/sci/gfx/gfx_tools.h
scummvm/trunk/engines/sci/gfx/gfx_widgets.h
scummvm/trunk/engines/sci/gfx/menubar.h
scummvm/trunk/engines/sci/gfx/operations.h
scummvm/trunk/engines/sci/gfx/palette.h
scummvm/trunk/engines/sci/gfx/res_pic.cpp
scummvm/trunk/engines/sci/gfx/seq_decoder.h
Modified: scummvm/trunk/engines/sci/gfx/font.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/font.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/font.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -30,6 +30,8 @@
namespace Sci {
+/** @name Font operations and stuctures */
+/** @{ */
struct TextFragment {
const char *offset;
@@ -39,90 +41,109 @@
TextFragment(const char *o) : offset(o), length(0) {}
};
-
-struct gfx_bitmap_font_t { /* gfx_bitmap_font_t: Bitmap font information */
- int ID; /* Unique resource ID */
-
- int chars_nr; /* Numer of available characters */
-
- int *widths; /* chars_nr character widths, in pixels */
-
- int row_size; /* Byte size of each pixel row. For unscaled fonts, this is
- ** always 1, 2, or 4. Otherwise, it's a multiple of 4.
- */
-
- int line_height; /* Height of each text line (usually identical to height) */
- int height; /* Height for all characters, in pixel rows */
- int char_size; /* Amount of memory occupied by one character in data */
-
- byte *data; /* Font data, consisting of 'chars_nr' entries of 'height' rows
- ** of 'row_size' bytes. For each character ch, its first byte
- ** (the topmost row) is located at (data + (charsize * ch)), and
- ** its pixel width is widths[ch], provided that (ch < chars_nr).
- */
-
+/**
+ * Bitmap font information.
+ */
+struct gfx_bitmap_font_t {
+ int ID; /**< Unique resource ID */
+ int chars_nr; /**< Numer of available characters */
+ int *widths; /**< chars_nr character widths, in pixels */
+ int row_size; /**
+ * Byte size of each pixel row. For unscaled fonts,
+ * this is always 1, 2, or 4. Otherwise, it's a
+ * multiple of 4.
+ */
+ int line_height; /**
+ * Height of each text line (usually identical to
+ * height)
+ */
+ int height; /**< Height for all characters, in pixel rows */
+ int char_size; /**
+ * Amount of memory occupied by one character
+ * in data
+ */
+ byte *data; /**
+ * Font data, consisting of 'chars_nr' entries
+ * of 'height' rows of 'row_size' bytes. For each
+ * character ch, its first byte (the topmost row)
+ * is located at (data + (charsize * ch)), and its
+ * pixel width is widths[ch], provided that
+ * (ch < chars_nr).
+ */
};
-/*******************/
-/* Font operations */
-/*******************/
-
-/* SCI0, SCI01 and SCI1 all use the same font format. */
+/**
+ * Font handling flags.
+ *
+ * SCI0, SCI01 and SCI1 all use the same font format.
+ */
enum fontFlags {
- kFontCountWhitespace = 1 << 0, // In SQ3, whitespace is included in text size
- kFontNoNewlines = 1 << 1, // Don't treat newline characters
- kFontIgnoreLF = 1 << 2 // Interpret CR LF sequences as a single newline, rather than two
+ kFontCountWhitespace = 1 << 0, //!< In SQ3, whitespace is included in text size
+ kFontNoNewlines = 1 << 1, //!< Don't treat newline characters
+ kFontIgnoreLF = 1 << 2 //!< Interpret CR LF sequences as a single newline, rather than two
};
+/**
+ * Generates a bitmap font data structure from a resource.
+ *
+ * @param[in] id Resource ID of the resulting font
+ * @param[in] resource Pointer to the resource data
+ * @param[in] size Size of the resource block
+ * @return The resulting font structure, or NULL on error
+ */
gfx_bitmap_font_t *gfxr_read_font(int id, byte *resource, int size);
-/* Generates a bitmap font data structure from a resource
-** Parameters: (int) id: Resource ID of the resulting font
-** (byte *) resource: Pointer to the resource data
-** (int) size: Size of the resource block
-** Returns : (gfx_bitmap_font_t *) The resulting font structure, or
-** NULL on error
-*/
+/**
+ * Frees a previously allocated font structure.
+ *
+ * @param font The font to free
+ */
void gfxr_free_font(gfx_bitmap_font_t *font);
-/* Frees a previously allocated font structure
-** Parameters: (gfx_bitmap_font_t *) font: The font to free
-** Returns : (void)
-*/
+/**
+ * Calculates the size that would be occupied by drawing a specified
+ * text.
+ *
+ * This function assumes 320x200 mode.
+ *
+ * @param[in] font The font to calculate with
+ * @param[in] max_width Maximum pixel width allowed for the output
+ * @param[in] text The text to calculate for
+ * @param[in] flags Any text formatting flags
+ * @param[out] fragments A newly allocated array of text_fragments,
+ * containing the start and size of each string
+ * segment.
+ * @param[out] width The resulting width
+ * @param[out] height The resulting height
+ * @param[out] line_height Pixel height of a single line of text
+ * @param[out] last_offset Pixel offset after the last drawn line
+ * @return true if successful, false otherwise
+ */
bool gfxr_font_calculate_size(Common::Array<TextFragment> &fragments,
gfx_bitmap_font_t *font, int max_width, const char *text,
int *width, int *height, int *line_height, int *last_offset, int flags);
-/* Calculates the size that would be occupied by drawing a specified text
-** Parameters: (gfx_bitmap_font_t *) font: The font to calculate with
-** (int) max_width: Maximum pixel width allowed for the output
-** (const char *) text: The text to calculate for
-** (int) flags: Any text formatting flags
-** Returns : (text_fragment *) a newly allocated array of text_fragments,
-** containing the start and size of each string
-** segment
-** (int) *width: The resulting width
-** (int) *height: The resulting height
-** (int) *line_height: Pixel height of a single line of text
-** (int) *last_offset: Pixel offset after the last drawn line
-** This function assumes 320x200 mode.
-*/
-gfx_pixmap_t *gfxr_draw_font(gfx_bitmap_font_t *font, const char *text, int characters,
- PaletteEntry *fg0, PaletteEntry *fg1, PaletteEntry *bg);
-/* Draws text in a specific font to a pixmap
-** Parameters: (gfx_bitmap_font_t *) font: The font to use for drawing
-** (char *) text: The start of the text to draw
-** (int) characters: The number of characters to draw
-** (gfx_pixmap_color_t *) fg0: The first foreground color
-** (gfx_pixmap_color_t *) fg1: The second foreground color
-** (gfx_pixmap_color_t *) bg: The background color
-** Returns : (gfx_pixmap_t *) The result pixmap, or NULL on error
-** The results are written to the pixmap's index buffer. Contents of the
-** foreground and background fields are copied into a newly allocated font
-** structure, so that the pixmap may be translated directly.
-** If any of the colors is null, it will be assumed to be transparent.
-** In color index mode, the specified colors have to be preallocated.
-*/
+/**
+ * Draws text in a specific font to a pixmap.
+ *
+ * The results are written to the pixmap's index buffer. Contents of the
+ * foreground and background fields are copied into a newly allocated font
+ * structure, so that the pixmap may be translated directly. If any of the
+ * colors is null, it will be assumed to be transparent.
+ * In color index mode, the specified colors have to be preallocated.
+ *
+ * @param[in] font The font to use for drawing
+ * @param[in] text The start of the text to draw
+ * @param[in] characters The number of characters to draw
+ * @param[in] fg0 The first foreground color
+ * @param[in] fg1 The second foreground color
+ * @param[in] bg The background color
+ * @return The result pixmap, or NULL on error
+ */
+gfx_pixmap_t *gfxr_draw_font(gfx_bitmap_font_t *font, const char *text,
+ int characters, PaletteEntry *fg0, PaletteEntry *fg1,
+ PaletteEntry *bg);
+/** @} */
} // End of namespace Sci
Modified: scummvm/trunk/engines/sci/gfx/gfx_driver.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_driver.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_driver.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -38,171 +38,202 @@
};
-/* Principial graphics driver architecture
-** ---------------------------------------
-**
-** All graphics drivers must provide
-** - One visual front buffer (the actually visible thing)
-** - Two dynamic back buffers:
-** + visual
-** + priority
-** - Two static buffers (containing the background image and picviews):
-** + visual
-** + priority
-**
-** The control buffer is handled outside the graphics driver architecture.
-** Graphics are drawn by first setting the static buffers, then updating
-** the back buffers (from the static buffers), adding all picviews and other
-** widgets, and finally updating the front buffer.
-**
-** All coordinates refer to the scaled coordinate system.
-** Invalid parameters should produce an error message.
-** Support for some valid parameter values is optional (like different line
-** modes). If an unsupported but valid parameter is specified, the function
-** must use a reasonable default value.
-*/
-
+/**
+ * Graphics driver.
+ *
+ * Principial graphics driver architecture:
+ *
+ * All graphics drivers must provide
+ * - One visual front buffer (the actually visible thing)
+ * - Two dynamic back buffers:
+ * - visual
+ * - priority
+ * - Two static buffers (containing the background image and picviews):
+ * - visual
+ * - priority
+ *
+ * The control buffer is handled outside the graphics driver architecture.
+ * Graphics are drawn by first setting the static buffers, then updating
+ * the back buffers (from the static buffers), adding all picviews and other
+ * widgets, and finally updating the front buffer.
+ *
+ * All coordinates refer to the scaled coordinate system.
+ * Invalid parameters should produce an error message.
+ * Support for some valid parameter values is optional (like different line
+ * modes). If an unsupported but valid parameter is specified, the function
+ * must use a reasonable default value.
+ */
class GfxDriver {
public:
- /*** Initialization ***/
-
+ /** @name Initialization */
+ /** @{ */
+ /**
+ * Attempts to initialize a specific graphics mode.
+ *
+ * The scaling factors apply to the standard SCI resolution of 320x200
+ * pixels and is used for internal representation of graphical data.
+ * The physical resolution set by the graphics driver may be different
+ * for practical reasons.
+ * Must also set _mode, preferably with the gfx_new_mode() function
+ * specified in gfx_tools.h.
+ *
+ * @param[in] xfact Horizontal scaling factor
+ * @param[in] yfact Vertical scaling factor
+ * @param[in] bytespp Any of GFX_COLOR_MODE_*. GFX_COLOR_MODE_INDEX
+ * implies color index mode.
+ * @return GFX_OK on success, GFX_ERROR if the mode could
+ * not be set, or GFX_FATAL if the graphics target
+ * is unuseable.
+ */
GfxDriver(int xfact, int yfact, int bytespp);
- /* Attempts to initialize a specific graphics mode
- ** Parameters: (int x int) xres, yres: Horizontal and vertical scaling
- ** factors
- ** (int) bytespp: Any of GFX_COLOR_MODE_*. GFX_COLOR_MODE_INDEX
- ** implies color index mode.
- ** Returns : (int) GFX_OK on success, GFX_ERROR if the mode could not be
- ** set, or GFX_FATAL if the graphics target is unuseable.
- ** The scaling factors apply to the standard SCI resolution of 320x200 pixels
- ** and is used for internal representation of graphical data. The physical
- ** resolution set by the graphics driver may be different for practical
- ** reasons.
- ** Must also set _mode, preferably with the gfx_new_mode() function
- ** specified in gfx_tools.h.
- */
+ /**
+ * Uninitializes the current graphics mode.
+ *
+ * This function frees all memory allocated by the graphics driver,
+ * including mode and palette information, uninstalls all console
+ * commands introduced by preceeding init() or init_specific()
+ * commands, and does any clean-up work (like closing visuals or
+ * returning to text mode) required by the graphics infrastructure used.
+ */
~GfxDriver();
- /* Uninitializes the current graphics mode
- ** This function frees all memory allocated by the graphics driver,
- ** including mode and palette information, uninstalls all console commands
- ** introduced by preceeding init() or init_specific() commands, and does any
- ** clean-up work (like closing visuals or returning to text mode) required by
- ** the graphics infrastructure used.
- */
+ /** @} */
+ /** @name Drawing operations */
+ /** @{ */
- /*** Drawing operations ***/
-
+ /**
+ * Draws a single line to the back buffer.
+ *
+ * Note that color.priority is relevant and must be drawn if
+ * (color.mask & GFX_MASK_PRIORITY). Support for line modes other than
+ * GFX_LINE_MODE_FAST is optional. For non-fine lines, the coordinates
+ * provided describe the upper left corner of the pixels of the line
+ * to draw.line_style support is optional, if
+ * GFX_CAPABILITY_STIPPLED_LINES is not set.
+ *
+ * @param[in] start Starting point of the line to draw
+ * @param[in] end End point of the line to draw
+ * @param[in] color The color to draw with
+ * @param[in] line_mode Any of the line modes
+ * @param[in] line_style Any of the line styles
+ * @return GFX_OK or GFX_FATAL
+ */
int drawLine(Common::Point start, Common::Point end, gfx_color_t color,
gfx_line_mode_t line_mode, gfx_line_style_t line_style);
- /* Draws a single line to the back buffer.
- ** Parameters: (Common::Point) start: Starting point of the line to draw
- ** (Common::Point) end: End point of the line to draw
- ** (gfx_color_t *) color: The color to draw with
- ** (int) line_mode: Any of the line modes
- ** (int) line_style: Any of the line styles
- ** Returns : (int) GFX_OK or GFX_FATAL
- ** Note that color.priority is relevant and must be drawn if
- ** (color.mask & GFX_MASK_PRIORITY).
- ** Support for line modes other than GFX_LINE_MODE_FAST is optional.
- ** For non-fine lines, the coordinates provided describe the upper left
- ** corner of the pixels of the line to draw.
- ** line_style support is optional, if GFX_CAPABILITY_STIPPLED_LINES is not
- ** set.
- */
+ /**
+ * Draws a single filled and possibly shaded rectangle to the back
+ * buffer.
+ *
+ * Note that color.priority is relevant and must be drawn if
+ * (color.mask & GFX_MASK_PRIORITY). color2 is relevant only if
+ * shade_mode is not GFX_SHADE_FLAT. Support for shade modes other
+ * than GFX_SHADE_FLAT is optional.
+ *
+ * @param[in] rect The rectangle to draw
+ * @param[in] color1 The first color to draw with
+ * @param[in] color2 The second color to draw with
+ * @param[in] shade_mode Any of GFX_SHADE_*.
+ * @return GFX_OK or GFX_FATAL
+ */
int drawFilledRect(rect_t rect, gfx_color_t color1, gfx_color_t color2,
gfx_rectangle_fill_t shade_mode);
- /* Draws a single filled and possibly shaded rectangle to the back buffer.
- ** Parameters: (rect_t *) rect: The rectangle to draw
- ** (gfx_color_t *) color1, color2: The colors to draw with
- ** (int) shade_mode: Any of GFX_SHADE_*.
- ** Returns : (int) GFX_OK or GFX_FATAL
- ** Note that color.priority is relevant and must be drawn if
- ** (color.mask & GFX_MASK_PRIORITY).
- ** color2 is relevant only if shade_mode is not GFX_SHADE_FLAT.
- ** Support for shade modes other than GFX_SHADE_FLAT is optional.
- */
+ /** @} */
- /*** Pixmap operations ***/
+ /** @name Pixmap operations */
+ /** @{ */
+ /**
+ * Draws part of a pixmap to the static or back buffer.
+ *
+ * @param[in] pxm The pixmap to draw
+ * @param[in] priority The priority to draw with, or GFX_NO_PRIORITY
+ * to draw on top of everything without setting the
+ * priority back buffer.
+ * @param[in] src The pixmap-relative source rectangle
+ * @param[in] dest The destination rectangle
+ * @param[in] buffer One of GFX_BUFFER_STATIC and GFX_BUFFER_BACK
+ * @return GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was
+ * not (but should have been) registered.
+ */
int drawPixmap(gfx_pixmap_t *pxm, int priority,
rect_t src, rect_t dest, gfx_buffer_t buffer);
- /* Draws part of a pixmap to the static or back buffer
- ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to draw
- ** (int) priority: The priority to draw with, or GFX_NO_PRIORITY
- ** to draw on top of everything without setting the
- ** priority back buffer
- ** (rect_t) src: The pixmap-relative source rectangle
- ** (rect_t) dest: The destination rectangle
- ** (int) buffer: One of GFX_BUFFER_STATIC and GFX_BUFFER_BACK
- ** Returns : (int) GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was not
- ** (but should have been) registered.
- */
+ /**
+ * Grabs an image from the visual or priority back buffer.
+ *
+ * This function is now mandatory.
+ *
+ * @param[in] src The rectangle to grab
+ * @param[in] pxm The pixmap structure the data is to be written to
+ * @param[in] map GFX_MASK_VISUAL or GFX_MASK_PRIORITY
+ * @return GFX_OK, GFX_FATAL, or GFX_ERROR for invalid map
+ * values pxm may be assumed to be empty and
+ * pre-allocated with an appropriate memory size.
+ */
int grabPixmap(rect_t src, gfx_pixmap_t *pxm, gfx_map_mask_t map);
- /* Grabs an image from the visual or priority back buffer
- ** Parameters: (rect_t) src: The rectangle to grab
- ** (gfx_pixmap_t *) pxm: The pixmap structure the data is to
- ** be written to
- ** (int) map: GFX_MASK_VISUAL or GFX_MASK_PRIORITY
- ** Returns : (int) GFX_OK, GFX_FATAL, or GFX_ERROR for invalid map values
- ** pxm may be assumed to be empty and pre-allocated with an appropriate
- ** memory size.
- ** This function is now mandatory.
- */
+ /** @} */
+ /** @name Buffer operations */
+ /** @{ */
- /*** Buffer operations ***/
-
+ /**
+ * Updates the front buffer or the back buffers.
+ *
+ * This function updates either the visual front buffer, or the two
+ * back buffers, by copying the specified source region to the
+ * destination region.
+ * For heuristical reasons, it may be assumed that the x and y fields
+ * of src and dest will be identical in /most/ cases.If they aren't,
+ * the priority map will not be required to be copied.
+ *
+ * @param[in] src: Source rectangle
+ * @param[in] dest: Destination point
+ * @param[in] buffer: One of GFX_BUFFER_FRONT or GFX_BUFFER_BACK
+ * @return GFX_OK, GFX_ERROR or GFX_FATAL
+ */
int update(rect_t src, Common::Point dest, gfx_buffer_t buffer);
- /* Updates the front buffer or the back buffers
- ** Parameters: (rect_t) src: Source rectangle
- ** (Common::Point) dest: Destination point
- ** (int) buffer: One of GFX_BUFFER_FRONT or GFX_BUFFER_BACK
- ** Returns : (int) GFX_OK, GFX_ERROR or GFX_FATAL
- ** This function updates either the visual front buffer, or the two back
- ** buffers, by copying the specified source region to the destination
- ** region.
- ** For heuristical reasons, it may be assumed that the x and y fields of
- ** src and dest will be identical in /most/ cases.
- ** If they aren't, the priority map will not be required to be copied.
- */
+ /**
+ * Sets the contents of the static visual and priority buffers.
+ *
+ * pic and priority may be modified or written to freely. They may also
+ * be used as the actual static buffers, since they are not freed and
+ * reallocated between calls to set_static_buffer() and update(),
+ * unless exit() was called in between.
+ * Note that later version of the driver interface may disallow
+ * modifying pic and priority. pic and priority are always scaled to
+ * the appropriate resolution
+ *
+ * @param[in] pic The image defining the new content of the
+ * visual back buffer
+ * @param[in] priority The priority map containing the new content of
+ * the priority back buffer in the index buffer
+ * @return GFX_OK or GFX_FATAL
+ */
int setStaticBuffer(gfx_pixmap_t *pic, gfx_pixmap_t *priority);
- /* Sets the contents of the static visual and priority buffers
- ** Parameters: (gfx_pixmap_t *) pic: The image defining the new content
- ** of the visual back buffer
- ** (gfx_pixmap_t *) priority: The priority map containing
- ** the new content of the priority back buffer
- ** in the index buffer
- ** Returns : (int) GFX_OK or GFX_FATAL
- ** pic and priority may be modified or written to freely. They may also be
- ** used as the actual static buffers, since they are not freed and re-
- ** allocated between calls to set_static_buffer() and update(), unless
- ** exit() was called in between.
- ** Note that later version of the driver interface may disallow modifying
- ** pic and priority.
- ** pic and priority are always scaled to the appropriate resolution
- */
+ /** @} */
+ /** @name Mouse pointer operations */
+ /** @{ */
- /*** Mouse pointer operations ***/
-
+ /**
+ * Sets a new mouse pointer.
+ *
+ * If pointer is not NULL, it will have been scaled to the appropriate
+ * size and registered as a pixmap (if neccessary) beforehand. If this
+ * function is called for a target that supports only two-color
+ * pointers, the image is a color index image, where only color index
+ * values 0, 1, and GFX_COLOR_INDEX_TRANSPARENT are used.
+ *
+ * @param[in] pointer The pointer to set, or NULL to set no pointer.
+ * @param[in] hotspot The coordinates of the hotspot, or NULL to set
+ * no pointer.
+ * @return GFX_OK or GFX_FATAL
+ */
int setPointer(gfx_pixmap_t *pointer, Common::Point *hotspot);
- /* Sets a new mouse pointer.
- ** Parameters: (gfx_pixmap_t *) pointer: The pointer to set, or NULL to set
- ** no pointer
- ** (Common::Point *) hotspot: The coordinates of the hotspot,
- ** or NULL to set no pointer
- ** Returns : (int) GFX_OK or GFX_FATAL
- ** If pointer is not NULL, it will have been scaled to the appropriate
- ** size and registered as a pixmap (if neccessary) beforehand.
- ** If this function is called for a target that supports only two-color
- ** pointers, the image is a color index image, where only color index values
- ** 0, 1, and GFX_COLOR_INDEX_TRANSPARENT are used.
- */
+ /** @} */
gfx_mode_t *getMode() { return _mode; }
byte *getVisual0() { return _visual[0]; }
@@ -212,7 +243,7 @@
gfx_pixmap_t *_priority[2];
byte *_visual[2];
- gfx_mode_t *_mode; /* Currently active mode, NULL if no mode is active */
+ gfx_mode_t *_mode; /**< Currently active mode, NULL if no mode is active */
};
} // End of namespace Sci
Modified: scummvm/trunk/engines/sci/gfx/gfx_gui.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_gui.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_gui.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -23,8 +23,6 @@
*
*/
-/* SCI-specific widget handling */
-
#ifndef SCI_INCLUDE_SCI_WIDGETS_H
#define SCI_INCLUDE_SCI_WIDGETS_H
@@ -34,152 +32,196 @@
class Menu;
-// The following flags are applicable to windows in SCI0
+/* SCI-specific widget handling */
+
+/**
+ * Flags for windows in SCI0.
+ */
enum windowFlags {
- kWindowTransparent = 0x01, // 0000 0001
- kWindowNoFrame = 0x02, // 0000 0010 - a window without a frame
- // Add title bar to window (10 pixels high, framed, text is centered and written in white on dark gray)
- kWindowTitle = 0x04, // 0000 0100
- // bits 3-6 are unused
- kWindowDontDraw = 0x80, // 1000 0000 - don't draw anything
- kWindowNoDropShadow = 0x1000000, // 0001 0000 0000 0000 0000 0000 0000 (not in SCI)
+ kWindowTransparent = 0x01, //!< 0000 0001
+ kWindowNoFrame = 0x02, //!< 0000 0010 - a window without a frame
+ kWindowTitle = 0x04, /**
+ * 0000 0100 - Add title bar to
+ * window (10 pixels high, framed,
+ * text is centered and written in
+ * white on dark gray), bits 3-6
+ * are unused
+ */
+ kWindowDontDraw = 0x80, //!< 1000 0000 - don't draw anything
+ kWindowNoDropShadow = 0x1000000, //!< 0001 0000 0000 0000 0000 0000 0000 (not in SCI)
kWindowAutoRestore = 0x2000000
};
+/** Button and frame control flags. */
enum controlStateFlags {
- kControlStateEnabled = 0x0001, // 0001 - enabled buttons (used by the interpreter)
- kControlStateDisabled = 0x0004, // 0010 - grayed out buttons (used by the interpreter)
- kControlStateFramed = 0x0008, // 1000 - widgets surrounded by a frame (used by the interpreter)
- kControlStateDitherFramed = 0x1000 // 0001 0000 0000 0000 - widgets surrounded by a dithered frame (used in kgraphics)
+ kControlStateEnabled = 0x0001, //!< 0001 - enabled buttons (used by the interpreter)
+ kControlStateDisabled = 0x0004, //!< 0010 - grayed out buttons (used by the interpreter)
+ kControlStateFramed = 0x0008, //!< 1000 - widgets surrounded by a frame (used by the interpreter)
+ kControlStateDitherFramed = 0x1000 //!< 0001 0000 0000 0000 - widgets surrounded by a dithered frame (used in kgraphics)
};
-void sciw_set_status_bar(EngineState *s, GfxPort *status_bar, const Common::String &text, int fgcolor, int bgcolor);
-/* Sets the contents of a port used as status bar
-** Parmeters: (EngineState *) s: The affected game state
-** (GfxPort *) status_bar: The status bar port
-** (const char *) text: The text to draw
-** Returns : (void)
-*/
+/**
+ * Sets the contents of a port used as status bar.
+ *
+ * @param[in] s The affected EngineState
+ * @param[in] status_bar The status bar port
+ * @param[in] text The text to draw
+ * @param[in] fgcolor The foreground color
+ * @param[in] bgcolor The background color
+ */
+void sciw_set_status_bar(EngineState *s, GfxPort *status_bar,
+ const Common::String &text, int fgcolor, int bgcolor);
-GfxPort *sciw_new_window(EngineState *s, rect_t area, int font, gfx_color_t color, gfx_color_t bgcolor,
- int title_font, gfx_color_t title_color, gfx_color_t title_bg_color,
- const char *title, int flags);
-/* Creates a new SCI style window
-** Parameters: (EngineState *) s: The affected game state
-** (rect_t) area: The screen area to frame (not including a potential window title)
-** (int) font: Default font number to use
-** (gfx_color_t) color: The foreground color to use for drawing
-** (gfx_color_t) bgcolor: The background color to use
-** (int) title_font: The font to use for the title bar (if any)
-** (gfx_color_t) title_color: Color to use for the title bar text
-** (gfx_color_t) title_bg_color: Color to use for the title bar background
-** (const char *) title: The text to write into the title bar
-** (int) flags: Any ORred combination of window flags
-** Returns : (GfxPort *) A newly allocated port with the requested characteristics
-*/
+/**
+ * Creates a new SCI style window.
+ *
+ * @param[in] s The affected EngineState
+ * @param[in] area The screen area to frame (not including a
+ * potential window title)
+ * @param[in] font Default font number to use
+ * @param[in] color The foreground color to use for drawing
+ * @param[in] bgcolor The background color to use
+ * @param[in] title_font The font to use for the title bar (if any)
+ * @param[in] title_color Color to use for the title bar text
+ * @param[in] title_bg_color Color to use for the title bar background
+ * @param[in] title The text to write into the title bar
+ * @param[in] flags Any ORred combination of window flags
+ * @return A newly allocated port with the requested characteristics
+ */
+GfxPort *sciw_new_window(EngineState *s, rect_t area, int font,
+ gfx_color_t color, gfx_color_t bgcolor, int title_font,
+ gfx_color_t title_color, gfx_color_t title_bg_color,
+ const char *title, int flags);
-/*---------------------*/
-/*** Control widgets ***/
-/*---------------------*/
-GfxList *sciw_new_button_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font, char selected, char inverse, char gray);
-/* Creates a new button control list
-** Parameters: (GfxPort *) port: The port containing the color values to use for the
-** button (the button is /not/ appended to the port there)
-** (reg_t) ID: Button's ID
-** (rect_t) zone: The area occupied by the button
-** (char *) text: The text to write into the button
-** (int) font: The font to use for the button
-** (char) selected: Whether the button should be marked as being selected by the keyboard focus
-** (char) inverse: Whether to inverse the color scheme
-** (char) gray: Whether the button should be grayed out
-** Returns : (GfxList *) The button
-*/
+/** @name Control widgets */
+/** @{ */
+/**
+ * Creates a new button control list.
+ *
+ * @param[in] port The port containing the color values to use for the
+ * button (the button is /not/ appended to the port
+ * there)
+ * @param[in] ID Button's ID
+ * @param[in] zone The area occupied by the button
+ * @param[in] text The text to write into the button
+ * @param[in] font The font to use for the button
+ * @param[in] selected Whether the button should be marked as being
+ * selected by the keyboard focus
+ * @param[in] inverse Whether to inverse the color scheme
+ * @param[in] gray Whether the button should be grayed out
+ * @return The button
+ */
+GfxList *sciw_new_button_control(GfxPort *port, reg_t ID, rect_t zone,
+ char *text, int font, char selected, char inverse, char gray);
-GfxList *sciw_new_text_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font,
- gfx_alignment_t align, char frame, char inverse);
-/* Creates a new text control list
-** Parameters: (GfxPort *) port: The port containing the color values to use
-** (reg_t) ID: Text widget ID
-** (rect_t) zone: Area occupied by the text
-** (char *) text: The text
-** (int) font: The font the text is to be drawn in
-** (gfx_alignment_t) align: Horizontal text alignment to use
-** (char) frame: Whether a dithered frame should surround the text
-** (char) inverse: Whether the text colors should be inversed
-** Returns : (GfxList *) The text control widget list
-*/
+/**
+ * Creates a new text control list.
+ *
+ * @param[in] port The port containing the color values to use
+ * @param[in] ID Text widget ID
+ * @param[in] zone Area occupied by the text
+ * @param[in] text The text
+ * @param[in] font The font the text is to be drawn in
+ * @param[in] align Horizontal text alignment to use
+ * @param[in] frame Whether a dithered frame should surround the text
+ * @param[in] inverse Whether the text colors should be inversed
+ * @return The text control widget list
+ */
+GfxList *sciw_new_text_control(GfxPort *port, reg_t ID, rect_t zone,
+ char *text, int font, gfx_alignment_t align, char frame,
+ char inverse);
-GfxList *sciw_new_edit_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font, unsigned int cursor,
- char inverse);
-/* Creates a new edit control list
-** Parameters: (GfxPort *) port: The port containing the color values to use
-** (reg_t) ID: Text widget ID
-** (rect_t) zone: Area occupied by the text
-** (char *) text: The text
-** (int) font: The font the text is to be drawn in
-** (int) cursor: Cursor position
-** (char) inverse: Whether the edit widget should be reversed
-** Returns : (GfxList *) An appropriate widget list
-*/
+/**
+ * Creates a new edit control list.
+ *
+ * @param[in] port The port containing the color values to use
+ * @param[in] ID Text widget ID
+ * @param[in] zone Area occupied by the text
+ * @param[in] text The text
+ * @param[in] font The font the text is to be drawn in
+ * @param[in] cursor Cursor position
+ * @param[in] inverse Whether the edit widget should be reversed
+ * @return An appropriate widget list
+ */
+GfxList *sciw_new_edit_control(GfxPort *port, reg_t ID, rect_t zone,
+ char *text, int font, unsigned int cursor, char inverse);
-GfxList *sciw_new_icon_control(GfxPort *port, reg_t ID, rect_t zone, int view, int loop, int cel,
- char frame, char inverse);
-/* Creates a new icon control list
-** Parameters: (GfxPort *) port: The port containing the color values to use
-** (reg_t) ID: Text widget ID
-** (rect_t) zone: Area occupied by the text
-** (int x int x int) view, loop, cel: The cel to display
-** (char) frame: Whether the widget should be surrounded by a frame
-** (char) lina inverse: Whether colors should be inversed
-** Returns : (GfxList *) An appropriate widget list
-*/
+/**
+ * Creates a new icon control list.
+ *
+ * @param[in] port The port containing the color values to use
+ * @param[in] ID Text widget ID
+ * @param[in] zone Area occupied by the text
+ * @param[in] view The view index
+ * @param[in] loop The loop index
+ * @param[in] cel The cel to display
+ * @param[in] frame Whether the widget should be surrounded by a frame
+ * @param[in] inverse Whether colors should be inversed
+ * @return An appropriate widget list
+ */
+GfxList *sciw_new_icon_control(GfxPort *port, reg_t ID, rect_t zone,
+ int view, int loop, int cel, char frame, char inverse);
-GfxList *sciw_new_list_control(GfxPort *port, reg_t ID, rect_t zone, int font_nr, char **entries_list,
- int entries_nr, int list_top, int selection, char inverse);
-/* Creates a new list control list
-** Parameters: (GfxPort *) port: The port containing the color values to use
-** (int) ID: Text widget ID
-** (rect_t) zone: Area occupied by the text
-** (int) font_nr: number of the font to use
-** (char **) entries_list: List of strings to contain within the list
-** (int) entries_nr: Number of entries in entries_list
-** (int) list_top: First list item that is visible
-** (int) selection: The list item that is selected
-** (char) invserse: The usual meaning
-** Returns : (GfxList *) An appropriate widget list
-*/
+/**
+ * Creates a new list control list.
+ *
+ * @param[in] port: The port containing the color values to use
+ * @param[in] ID: Text widget ID
+ * @param[in] zone: Area occupied by the text
+ * @param[in] font_nr: Number of the font to use
+ * @param[in] entries_list: List of strings to contain within the list
+ * @param[in] entries_nr: Number of entries in entries_list
+ * @param[in] list_top: First list item that is visible
+ * @param[in] selection: The list item that is selected
+ * @param[in] inverse: The usual meaning
+ * @return An appropriate widget list
+ */
+GfxList *sciw_new_list_control(GfxPort *port, reg_t ID, rect_t zone,
+ int font_nr, char **entries_list, int entries_nr, int list_top,
+ int selection, char inverse);
+/** @} */
-/*---------------------*/
-/*** Menubar widgets ***/
-/*---------------------*/
+/** @name Menubar widgets */
+/** @{ */
-void sciw_set_menubar(EngineState *s, GfxPort *status_bar, Menubar *menubar, int selection);
-/* Draws the menu bar
-** Parameters: (EngineState *) s: The state to operate on
-** (GfxPort *) status_bar: The status bar port to modify
-** (Menubar *) menubar: The menu bar to use
-** (int) selection: Number of the menu to hightlight, or -1 for 'none'
-** Returns : (void)
-*/
+/**
+ * Draws the menu bar.
+ *
+ * @param[in] s: The EngineState to operate on
+ * @param[in] status_bar: The status bar port to modify
+ * @param[in] menubar: The menu bar to use
+ * @param[in] selection: Number of the menu to hightlight, or -1 for
+ * 'none'
+ */
+void sciw_set_menubar(EngineState *s, GfxPort *status_bar, Menubar *menubar,
+ int selection);
-GfxPort *sciw_new_menu(EngineState *s, GfxPort *status_bar, Menubar *menubar, int selection);
-/* Creates a menu port
-** Parameters: (EngineState *) s: The state to operate on
-** (GfxPort *) status_bar: The status bar
-** (Menubar *) menubar: The menu bar to use
-** (int) selection: Number of the menu to interpret
-** Returns : (GfxPort *) The result port
-*/
+/**
+ * Creates a menu port.
+ *
+ * @param[in] s The state to operate on
+ * @param[in] status_bar The status bar
+ * @param[in] menubar The menu bar to use
+ * @param[in] selection Number of the menu to interpret
+ * @return The result port
+ */
+GfxPort *sciw_new_menu(EngineState *s, GfxPort *status_bar,
+ Menubar *menubar, int selection);
-GfxPort *sciw_toggle_item(GfxPort *menu_port, Menu *menu, int selection, bool selected);
-/* Toggle the selection of a menu item from a menu port
-** Parameters: (GfxPort *) menu_port: The port to modify
-** (Menu *) menu: The menu the menu port corresponds to
-** (int) selection: Number of the menu entry to unselect, or -1 to do a NOP
-** (bool) selected: Whether to set the item's state to selected or not
-** Returns : (GfxPort *) The modified menu
-*/
+/**
+ * Toggle the selection of a menu item from a menu port.
+ *
+ * @param[in] menu_port The port to modify
+ * @param[in] menu The menu the menu port corresponds to
+ * @param[in] selection Number of the menu entry to unselect, or -1 to do
+ * a NOP
+ * @param[in] selected Whether to set the item's state to selected or not
+ * @return The modified menu
+ */
+GfxPort *sciw_toggle_item(GfxPort *menu_port, Menu *menu, int selection,
+ bool selected);
+/** @} */
} // End of namespace Sci
Modified: scummvm/trunk/engines/sci/gfx/gfx_options.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_options.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_options.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -42,20 +42,20 @@
namespace Sci {
-/* Dirty rectangle heuristics: */
+/** Dirty rectangle heuristics. */
+enum {
+ GFXOP_DIRTY_FRAMES_ONE = 1, /**< One: Redraw one rectangle surrounding the dirty area (insert is O(1)) */
+ GFXOP_DIRTY_FRAMES_CLUSTERS = 2 /**< Clusters: Accumulate dirty rects, merging those that overlap (insert is O(n)) */
+};
-/* One: Redraw one rectangle surrounding the dirty area (insert is O(1)) */
-#define GFXOP_DIRTY_FRAMES_ONE 1
-
-/* Clusters: Accumulate dirty rects, merging those that overlap (insert is O(n)) */
-#define GFXOP_DIRTY_FRAMES_CLUSTERS 2
-
+/**
+ * All user options to the rendering pipeline
+ *
+ * See note in sci_conf.h for config_entry_t before changing types of
+ * variables
+ */
struct gfx_options_t {
#ifdef CUSTOM_GRAPHICS_OPTIONS
- /* gfx_options_t: Contains all user options to the rendering pipeline */
- /* See note in sci_conf.h for config_entry_t before changing types of
- ** variables */
-
int buffer_pics_nr; /* Number of unused pics to buffer */
/* SCI0 pic resource options */
Modified: scummvm/trunk/engines/sci/gfx/gfx_res_options.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_res_options.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_res_options.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -23,8 +23,6 @@
*
*/
-/* Configuration options for per-resource customisations */
-
#ifndef SCI_GFX_GFX_RES_OPTIONS_H
#define SCI_GFX_GFX_RES_OPTIONS_H
@@ -35,13 +33,16 @@
#include "sci/gfx/gfx_resmgr.h"
namespace Sci {
+/** @name Configuration options for per-resource customisations */
+/** @{ */
struct gfx_res_pattern_t {
int min, max;
};
-/* GFX resource assignments */
-
+/**
+ * GFX resource assignments.
+ */
struct gfx_res_assign_t {
union {
struct {
@@ -52,23 +53,24 @@
};
-/* GFX resource modifications */
-
+/**
+ * GFX resource modifications/
+ */
struct gfx_res_conf_t {
- int type; /* Resource type-- only one allowed */
+ int type; /**< Resource type-- only one allowed */
/* If any of the following is 0, it means that there is no restriction.
** Otherwise, one of the patterns associated with them must match. */
- int patterns_nr; /* Number of patterns (only 'view' patterns for views) */
- int loops_nr, cels_nr; /* Number of loop/cel patterns, for views only.
+ int patterns_nr; /**< Number of patterns (only 'view' patterns for views) */
+ int loops_nr, cels_nr; /**< Number of loop/cel patterns, for views only.
** For pics, loops_nr identifies the palette. */
gfx_res_pattern_t *patterns;
union {
gfx_res_assign_t assign;
- byte factor[3]; /* divide by 16 to retrieve factor */
- } conf; /* The actual configuration */
+ byte factor[3]; /**< divide by 16 to retrieve factor */
+ } conf; /**< The actual configuration */
gfx_res_conf_t *next;
};
@@ -84,16 +86,20 @@
struct gfx_options_t;
+/**
+ * Configures a graphical pixmap according to config options.
+ *
+ * Modifies pxm as considered appropriate by configuration options. Does
+ * not do anything in colour index mode.
+ *
+ * @param[in] options The options according to which configuration
+ * should be performed
+ * @param[in] pxm The pixmap to configure
+ * @return 0 on success, non-zero otherwise
+ */
int gfx_get_res_config(gfx_options_t *options, gfx_pixmap_t *pxm);
-/* Configures a graphical pixmap according to config options
-** Parameters: (gfx_options_t *) options: The options according to which
-** configuration should be performed
-** (gfx_resource_type_t) pxm: The pixmap to configure
-** Returns : (int) 0 on success, non-zero otherwise
-** Modifies pxm as considered appropriate by configuration options. Does
-** not do anything in colour index mode.
-*/
+/** @} */
} // End of namespace Sci
#endif
Modified: scummvm/trunk/engines/sci/gfx/gfx_resmgr.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_resmgr.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_resmgr.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -49,7 +49,7 @@
GFX_RESOURCE_TYPE_PALETTE,
/* FIXME: Add PAL resource */
- GFX_RESOURCE_TYPES_NR /* Number of resource types that are to be supported */
+ GFX_RESOURCE_TYPES_NR /**< Number of resource types that are to be supported */
};
#define GFX_RESOURCE_TYPE_0 GFX_RESOURCE_TYPE_VIEW
@@ -58,12 +58,13 @@
#define GFXR_RES_TYPE(id) (id >> 16)
#define GFXR_RES_NR(id) (id & 0xffff)
-
+/** Graphics resource */
struct gfx_resource_t {
- int ID; /* Resource ID */
- int lock_sequence_nr; /* See description of lock_counter in GfxResManager */
- int mode; /* A mode type hash */
+ int ID; /**< Resource ID */
+ int lock_sequence_nr; /**< See description of lock_counter in GfxResManager */
+ int mode; /**< A mode type hash */
+ /** Scaled pic */
union {
gfx_pixmap_t *pointer;
gfxr_view_t *view;
@@ -71,6 +72,7 @@
gfxr_pic_t *pic;
} scaled_data;
+ /** Original pic */
union {
gfx_pixmap_t *pointer;
gfxr_view_t *view;
@@ -85,152 +87,204 @@
typedef Common::HashMap<int, gfx_resource_t *> IntResMap;
-
+/** Graphics resource manager */
class GfxResManager {
public:
- GfxResManager(int version, bool isVGA, gfx_options_t *options, GfxDriver *driver, ResourceManager *resManager);
+ GfxResManager(int version, bool isVGA, gfx_options_t *options,
+ GfxDriver *driver, ResourceManager *resManager);
~GfxResManager();
- /* Calculates a unique hash value for the specified options/type setup
- ** Parameters: (gfx_resource_type_t) type: The type the hash is to be generated for
- ** Returns : (int) A hash over the values of the options entries, covering entries iff
- ** they are relevant for the specified type
- ** Covering more entries than relevant may slow down the system when options are changed,
- ** while covering less may result in invalid cached data being used.
- ** Only positive values may be returned, as negative values are used internally by the generic
- ** resource manager code.
- ** Also, only the lower 20 bits are available to the interpreter.
- ** (Yes, this isn't really a "hash" in the traditional sense...)
- */
+ /**
+ * Calculates a unique hash value for the specified options/type
+ * setup.
+ *
+ * Covering more entries than relevant may slow down the system when
+ * options are changed, while covering less may result in invalid
+ * cached data being used.
+ * Only positive values may be returned, as negative values are used
+ * internally by the generic resource manager code.
+ * Also, only the lower 20 bits are available to the interpreter.
+ * (Yes, this isn't really a "hash" in the traditional sense...)
+ *
+ * @param[in] type The type the hash is to be generated for
+ * @return A hash over the values of the options entries,
+ * covering entries iff they are relevant for the
+ * specified type.
+ */
int getOptionsHash(gfx_resource_type_t type);
- /* 'Tags' all resources for deletion
- ** Paramters: (void)
- ** Returns : (void)
- ** Tagged resources are untagged if they are referenced.
- */
+ /**
+ * 'Tags' all resources for deletion.
+ *
+ * Tagged resources are untagged if they are referenced.
+ */
void tagResources() { _tagLockCounter++; }
- /* Retrieves an SCI0/SCI01 mouse cursor
- ** Parameters: (int) num: The cursor number
- ** Returns : (gfx_font_t *) The approprate cursor as a pixmap, or NULL on error
- */
+ /**
+ * Retrieves an SCI0/SCI01 mouse cursor.
+ *
+ * @param[in] num The cursor number
+ * @return The approprate cursor as a pixmap, or NULL on error
+ */
gfx_pixmap_t *getCursor(int num);
- /* Retrieves the static palette from the interpreter-specific code
- ** Parameters: (int *) colors_nr: Number of colors to use
- ** (int) nr: The palette to read
- ** Returns : (Palette *) static palette
- ** if a static palette must be used, NULL otherwise
- */
+ /**
+ * Retrieves the static palette from the interpreter-specific code.
+ *
+ * @param[in] colors_nr Number of colors to use
+ * @param[in] num The palette to read
+ * @return Static palette if a static palette must be
+ * used, NULL otherwise
+ */
Palette *getPalette(int *colors_nr, int num = 999);
- /* Retrieves a font
- ** Parameters: (int) nr: The font number
- ** (int) scaled: Whether the font should be font-scaled
- ** Returns : (gfx_font_t *) The appropriate font, or NULL on error
- */
+ /**
+ * Retrieves a font.
+ *
+ * @param[in] num The font number
+ * @param[in] scaled Whether the font should be font-scaled
+ * @return The appropriate font, or NULL on error
+ */
gfx_bitmap_font_t *getFont(int num, bool scaled = false);
- /* Retrieves a translated view cel
- ** Parameters:
- ** (int) nr: The view number
- ** (int *) loop: Pointer to a variable containing the loop number
- ** (int *) cel: Pointer to a variable containing the cel number
- ** (int) palette: The palette to use
- ** Returns : (gfx_view_t *) The relevant view, or NULL if nr was invalid
- ** loop and cel are given as pointers in order to allow the underlying variables to be
- ** modified if they are invalid (this is relevant for SCI version 0, where invalid
- ** loop and cel numbers have to be interpreted as 'maximum' or 'minimum' by the interpreter)
- */
+ /**
+ * Retrieves a translated view cel.
+ *
+ * @param[in] nr The view number
+ * @param[in] loop Pointer to a variable containing the loop number
+ * @param[in] cel Pointer to a variable containing the cel number
+ * @param[in] palette The palette to use
+ * @return The relevant view, or NULL if nr was invalid
+ * loop and cel are given as pointers in order to
+ * allow the underlying variables to be modified
+ * if they are invalid (this is relevant for SCI
+ * version 0, where invalid loop and cel numbers
+ * have to be interpreted as 'maximum' or 'minimum'
+ * by the interpreter)
+ */
gfxr_view_t *getView(int nr, int *loop, int *cel, int palette);
- /* Retrieves a displayable (translated) pic resource
- ** Parameters: (int) nr: Number of the pic resource
- ** (int) maps: The maps to translate (ORred GFX_MASK_*)
- ** (int) flags: Interpreter-dependant pic flags
- ** (int) default_palette: The default palette to use for drawing (if applicable)
- ** (bool) scaled: Whether to return the scaled maps, or the unscaled
- ** ones (which may be identical) for some special operations.
- ** Returns : (gfxr_pic_t *) The appropriate pic resource with all maps as index (but not
- ** neccessarily translated) data.
- */
- gfxr_pic_t *getPic(int num, int maps, int flags, int default_palette, bool scaled = false);
+ /**
+ * Retrieves a displayable (translated) pic resource.
+ *
+ * @param[in] num Number of the pic resource
+ * @param[in] maps The maps to translate (ORred GFX_MASK_*)
+ * @param[in] flags Interpreter-dependant pic flags
+ * @param[in] default_palette The default palette to use for drawing
+ * (if applicable)
+ * @param[in] scaled Whether to return the scaled maps, or
+ * the unscaled ones (which may be
+ * identical) for some special operations.
+ * @return The appropriate pic resource with all
+ * maps as index (but not neccessarily
+ * translated) data.
+ */
+ gfxr_pic_t *getPic(int num, int maps, int flags, int default_palette,
+ bool scaled = false);
- /* Retrieves a displayable (translated) pic resource written ontop of an existing pic
- ** Parameters: (int) old_nr: Number of the pic resource to write on
- ** (int) new_nr: Number of the pic resource that is to be added
- ** (int) flags: Interpreter-dependant pic flags
- ** (int) default_palette: The default palette to use for drawing (if applicable)
- ** (int) scaled: Whether to return the scaled maps, or the unscaled
- ** ones (which may be identical) for some special operations.
- ** Returns : (gfxr_pic_t *) The appropriate pic resource with all maps as index (but not
- ** neccessarily translated) data.
- ** This function invalidates the cached pic pointed to by old_nr in the cache. While subsequent
- ** addToPic() writes will still modify the 'invalidated' pic, gfxr_get_pic() operations will
- ** cause it to be removed from the cache and to be replaced by a clean version.
- */
- gfxr_pic_t *addToPic(int old_nr, int new_nr, int flags, int old_default_palette, int default_palette);
+ /**
+ * Retrieves a displayable (translated) pic resource written ontop of
+ * an existing pic.
+ *
+ * This function invalidates the cached pic pointed to by old_nr in the
+ * cache. While subsequent addToPic() writes will still modify the
+ * 'invalidated' pic, gfxr_get_pic() operations will cause it to be
+ * removed from the cache and to be replaced by a clean version.
+ *
+ * @param[in] old_nr Number of the pic resource to write on
+ * @param[in] new_nr Number of the pic resource that is to
+ * be added
+ * @param[in] flags Interpreter-dependant pic flags
+ * @param[in] old_default_palette The default palette of the pic before
+ * translation
+ * @param[in] default_palette The default palette to use for drawing
+ * (if applicable)
+ * @return The appropriate pic resource with all
+ * maps as index (but not neccessarily
+ * translated) data.
+ */
+ gfxr_pic_t *addToPic(int old_nr, int new_nr, int flags,
+ int old_default_palette, int default_palette);
- /* Calculate a picture
- ** Parameters: (gfxr_pic_t *) scaled_pic: The pic structure that is to be written to
- ** (gfxr_pic_t *) unscaled_pic: The pic structure the unscaled pic is to be written to,
- ** or NULL if it isn't needed.
- ** (int) flags: Pic drawing flags (interpreter dependant)
- ** (int) default_palette: The default palette to use for pic drawing (interpreter dependant)
- ** (int) nr: pic resource number
- ** Returns : (int) GFX_ERROR if the resource could not be found, GFX_OK otherwise
- */
- int calculatePic(gfxr_pic_t *scaled_pic, gfxr_pic_t *unscaled_pic, int flags, int default_palette, int nr);
+ /**
+ * Calculate a picture
+ *
+ * @param[in] scaled_pic The pic structure that is to be
+ * written to
+ * @param[in] unscaled_pic The pic structure the unscaled pic is
+ * to be written to, or NULL if it isn't
+ * needed.
+ * @param[in] flags Pic drawing flags (interpreter
+ * dependant)
+ * @param[in] default_palette The default palette to use for pic
+ * drawing (interpreter dependant)
+ * @param[in] nr pic resource number
+ * @return GFX_ERROR if the resource could not be
+ * found, GFX_OK otherwise
+ */
+ int calculatePic(gfxr_pic_t *scaled_pic, gfxr_pic_t *unscaled_pic,
+ int flags, int default_palette, int nr);
- /* Determines whether support for pointers with more than two colors is required
- ** Returns : (bool) false if no support for multi-colored pointers is required, true
- ** otherwise
- */
+ /**
+ * Determines whether support for pointers with more than two colors
+ * is required.
+ *
+ * @return false if no support for multi-colored pointers is required,
+ * true otherwise
+ */
bool multicoloredPointers() { return _version > SCI_VERSION_1; }
- /* Frees all resources currently allocated
- ** Parameter: (void)
- ** Returns : (void)
- ** This function is intended to be used primarily for debugging.
- */
+ /**
+ * Frees all resources currently allocated.
+ *
+ * This function is intended to be used primarily for debugging.
+ */
void freeAllResources();
- /* Frees all tagged resources.
- ** Parameters: (void)
- ** Returns : (void)
- ** Resources are tagged by calling gfx_tag_resources(), and untagged by calling the
- ** approprate dereferenciation function.
- ** Note that this function currently only affects view resources, as pic resources are
- ** treated differently, while font and cursor resources are relatively rare.
- */
+ /**
+ * Frees all tagged resources.
+ *
+ * Resources are tagged by calling gfx_tag_resources(), and untagged by
+ * calling the approprate dereferenciation function.
+ * Note that this function currently only affects view resources, as
+ * pic resources are treated differently, while font and cursor
+ * resources are relatively rare.
+ */
void freeTaggedResources();
- /* Frees a previously allocated resource manager, and all allocated resources.
- ** Parameters: (void)
- ** Return : (void)
- */
+ /**
+ * Frees a previously allocated resource manager, and all allocated
+ * resources.
+ */
void freeResManager();
- const PaletteEntry &getColor(int color) { return _staticPalette->getColor(color); }
+ /**
+ * Retrieves a color from the static palette
+ */
+ const PaletteEntry &getColor(int color)
+ {
+ return _staticPalette->getColor(color);
+ }
- // Set static palette and merge it into the global palette
+ /**
+ * Set static palette and merge it into the global palette
+ */
void setStaticPalette(Palette *newPalette);
- /*
- ** Sets the picture port bounds
- */
+ /**
+ * Sets the picture port bounds
+ */
void changePortBounds(int x1, int y1, int x2, int y2) {
_portBounds = Common::Rect(x1, y1, x2, y2);
}
@@ -252,7 +306,15 @@
}
#endif
- int getColorCount() { return _staticPalette ? _staticPalette->size() : 0; }
+ /**
+ * Gets the number of colors in the static palette.
+ *
+ * @return Number of pallete entries
+ */
+ int getColorCount()
+ {
+ return _staticPalette ? _staticPalette->size() : 0;
+ }
private:
int _version;
@@ -260,11 +322,11 @@
gfx_options_t *_options;
GfxDriver *_driver;
Palette *_staticPalette;
- int _lockCounter; /* Global lock counter; increased for each new resource allocated.
- ** The newly allocated resource will then be assigned the new value
- ** of the lock_counter, as will any resources referenced afterwards.
- */
- int _tagLockCounter; /* lock counter value at tag time */
+ int _lockCounter; /**< Global lock counter; increased for each new
+ * resource allocated. The newly allocated resource will
+ * then be assigned the new value of the lock_counter,
+ * as will any resources referenced afterwards. */
+ int _tagLockCounter; /**< lock counter value at tag time */
Common::Rect _portBounds;
IntResMap _resourceMaps[GFX_RESOURCE_TYPES_NR];
Modified: scummvm/trunk/engines/sci/gfx/gfx_resource.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_resource.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_resource.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -23,7 +23,9 @@
*
*/
-/* SCI Resource library */
+/** @file gfx_resource.h
+ * SCI Resource library.
+ */
#ifndef SCI_GFX_GFX_RESOURCE_H
#define SCI_GFX_GFX_RESOURCE_H
@@ -44,6 +46,7 @@
#define GFXR_DITHER_MODE_D16 0 /* Sierra SCI style */
#define GFXR_DITHER_MODE_F256 1 /* Flat color interpolation */
#define GFXR_DITHER_MODE_D256 2 /* 256 color dithering */
+
/* Dithering patterns */
#define GFXR_DITHER_PATTERN_SCALED 0 /* Dither per pixel on the 320x200 grid */
#define GFXR_DITHER_PATTERN_1 1 /* Dither per pixel on the target */
@@ -64,52 +67,53 @@
extern int sci0_palette;
-/* (gfx_pic_0.c) The 16 EGA base colors */
+/** The 16 EGA base colors */
extern Palette* gfx_sci0_image_pal[];
extern gfx_pixmap_color_t gfx_sci0_image_colors[][16];
-/* (gfx_pic_0.c) The 256 interpolated colors (initialized when
-** gfxr_init_pic() is called for the first time, or when gfxr_init_static_palette() is called)
-*/
+/**
+ * The 256 interpolated colors (initialized when gfxr_init_pic() is called
+ * for the first time, or when gfxr_init_static_palette() is called)
+ */
extern Palette* gfx_sci0_pic_colors;
-
struct gfxr_pic0_params_t {
gfx_line_mode_t line_mode; /* one of GFX_LINE_MODE_* */
gfx_brush_mode_t brush_mode;
};
+/** A SCI resource pic */
struct gfxr_pic_t {
- int ID; /* pic number (NOT resource ID, just number) */
+ int ID; /**< pic number (NOT resource ID, just number) */
gfx_mode_t *mode;
- gfx_pixmap_t *visual_map;
- gfx_pixmap_t *priority_map;
- gfx_pixmap_t *control_map;
+ gfx_pixmap_t *visual_map; /**< Visual part of pic */
+ gfx_pixmap_t *priority_map; /**< Priority map for pic */
+ gfx_pixmap_t *control_map; /**< Control map for pic */
+ /**
+ * Auxiliary map.
+ * Bit 0: Vis
+ * Bit 1: Pri
+ * Bit 2: Ctrl
+ * Bit 3-5: 'filled' (all three bits are set to 1)
+ */
byte aux_map[GFXR_AUX_MAP_SIZE];
- /* Auxiliary map details:
- ** Bit 0: Vis
- ** Bit 1: Pri
- ** Bit 2: Ctrl
- ** Bit 3-5: 'filled' (all three bits are set to 1)
- */
-
// rect_t bounds; // unused
- void *undithered_buffer; /* copies visual_map->index_data before dithering */
+ void *undithered_buffer; /**< copies visual_map->index_data before dithering */
int undithered_buffer_size;
int *priorityTable;
};
-
+/** A animation loop */
struct gfxr_loop_t {
- int cels_nr;
- gfx_pixmap_t **cels;
+ int cels_nr; /**< Number of 'cels' or frames in the animation */
+ gfx_pixmap_t **cels; /**< Pointer to the pixmaps for the cels */
};
-
+/** A graphics view */
struct gfxr_view_t {
int ID;
@@ -122,173 +126,198 @@
int translation[GFX_SCI0_IMAGE_COLORS_NR];
};
+/**
+ * Initializes the static 256 color palette.
+ */
void gfxr_init_static_palette();
-/* Initializes the static 256 color palette
-** Parameters: (void)
-** Returns : (void)
-*/
-gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, int sci1);
-/* Initializes a gfxr_pic_t for a specific mode
-** Parameters: (gfx_mode_t *) mode: The specific graphics mode
-** (int) ID: The ID to assign to the resulting pixmaps
-** Returns : (gfxr_pic_t *) The allocated pic resource, or NULL on error.
-** This function allocates memory for use by resource drawer functions.
-*/
+/** @name Resource picture management functions */
+/** @{ */
+/**
+ * Initializes a gfxr_pic_t for a specific mode.
+ *
+ * This function allocates memory for use by resource drawer functions.
+ *
+ * @param[in] mode The specific graphics mode
+ * @param[in] ID The ID to assign to the resulting pixmaps
+ * @param[in] sci1 true if a SCI1 pic, false otherwise
+ * @return The allocated pic resource, or NULL on error.
+ */
+gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, bool sci1);
+
+/**
+ * Uninitializes a pic resource.
+ *
+ * @param[in] pic The pic to free
+ */
void gfxr_free_pic(gfxr_pic_t *pic);
-/* Uninitializes a pic resource
-** Parameters: (gfxr_pic_t *) pic: The pic to free
-** Returns : (void)
-*/
+/**
+ * Frees all memory associated with a view.
+ *
+ * @param[in] view The view to free
+ */
void gfxr_free_view(gfxr_view_t *view);
-/* Frees all memory associated with a view
-** Paremeters: (gfxr_view_t *) view: The view to free
-** Returns : (void)
-*/
+/** @} */
+/** @name SCI0 resource picture operations */
+/** @{ */
-
-
-
-/*********************/
-/* SCI0 operations */
-/*********************/
-
-
+/**
+ * Clears all pic buffers of one pic/
+ *
+ * This function should be called before gfxr_draw_pic0, unless cumulative
+ * drawing is intended
+ *
+ * @param[in] pic The picture to clear
+ * @param[in] titlebar_size How much space to reserve for the title bar
+ */
void gfxr_clear_pic0(gfxr_pic_t *pic, int titlebar_size);
-/* Clears all pic buffers of one pic
-** Parameters: (gfxr_pic_t) pic: The picture to clear
-** (int) titlebar_size: How much space to reserve for the title bar
-** Returns : (void)
-** This function should be called before gfxr_draw_pic0, unless cumulative
-** drawing is intended
-*/
+/**
+ * Draws a pic resource (all formats prior to SCI1.1).
+ *
+ * The result is stored in gfxr_visual_map, gfxr_priority_map, and
+ * gfxr_control_map. The palette entry of gfxr_visual_map is never used.
+ * Note that the picture will not be drawn dithered; use gfxr_dither_pic0
+ * for that.
+ *
+ * @param[in] pic The pic to draw to
+ * @param[in] fill_normally If 1, the pic is drawn normally; if 0, all
+ * fill operations will fill with black
+ * @param[in] default_palette The default palette to use for drawing
+ * @param[in] size Resource size
+ * @param[in] resource Pointer to the resource data
+ * @param[in] style The drawing style
+ * @param[in] resid The resource ID
+ * @param[in] sci1 true if SCI1, false otherwise
+ * @param[in] static_pal The static palette
+ * @param[in] portBounds The bounds of the port being drawn to
+ */
+void gfxr_draw_pic01(gfxr_pic_t *pic, int fill_normally,
+ int default_palette, int size, byte *resource,
+ gfxr_pic0_params_t *style, int resid, int sci1,
+ Palette *static_pal, Common::Rect portBounds);
-void gfxr_draw_pic01(gfxr_pic_t *pic, int fill_normally, int default_palette,
- int size, byte *resource, gfxr_pic0_params_t *style, int resid, int sci1,
- Palette *static_pal, Common::Rect portBounds);
-/* Draws a pic resource (all formats prior to SCI1.1)
-** Parameters: (gfxr_pic_t *) pic: The pic to draw to
-** (int) fill_normally: If 1, the pic is drawn normally; if 0, all
-** fill operations will fill with black
-** (int) default_palette: The default palette to use for drawing
-** (int) size: Resource size
-** (byte *) resource: Pointer to the resource data
-** (gfxr_pic0_params_t *) style: The drawing style
-** (int) resid: The resource ID
-** (int) sci1: Nonzero if SCI1
-** (Palette *) static_pal: The static palette
-** (int) static_pal_nr: Number of entries in static palette
-** Returns : (void)
-** The result is stored in gfxr_visual_map, gfxr_priority_map, and gfxr_control_map.
-** The palette entry of gfxr_visual_map is never used.
-** Note that the picture will not be drawn dithered; use gfxr_dither_pic0 for that.
-*/
+/**
+ * Draws a pic resource (SCI1.1).
+ *
+ * The result is stored in gfxr_visual_map, gfxr_priority_map, and
+ * gfxr_control_map. The palette entry of gfxr_visual_map is never used.
+ * Note that the picture will not be drawn dithered; use gfxr_dither_pic11
+ * for that.
+ *
+ * @param[in] pic The pic to draw to
+ * @param[in] fill_normally If 1, the pic is drawn normally; if 0, all
+ * fill operations will fill with black
+ * @param[in] default_palette The default palette to use for drawing
+ * @param[in] size Resource size
+ * @param[in] resource Pointer to the resource data
+ * @param[in] style The drawing style
+ * @param[in] resid The resource ID
+ * @param[in] static_pal The static palette
+ * @param[in] portBounds Bounds of the port being drawn to
+ */
+void gfxr_draw_pic11(gfxr_pic_t *pic, int fill_normally,
+ int default_palette, int size, byte *resource,
+ gfxr_pic0_params_t *style, int resid, Palette *static_pal,
+ Common::Rect portBounds);
-void gfxr_draw_pic11(gfxr_pic_t *pic, int fill_normally, int default_palette,
- int size, byte *resource, gfxr_pic0_params_t *style, int resid,
- Palette *static_pal, Common::Rect portBounds);
-/* Draws a pic resource (SCI1.1)
-** Parameters: (gfxr_pic_t *) pic: The pic to draw to
-** (int) fill_normally: If 1, the pic is drawn normally; if 0, all
-** fill operations will fill with black
-** (int) default_palette: The default palette to use for drawing
-** (int) size: Resource size
-** (byte *) resource: Pointer to the resource data
-** (gfxr_pic0_params_t *) style: The drawing style
-** (int) resid: The resource ID
-** (Palette *) static_pal: The static palette
-** (int) static_pal_nr: Number of entries in static palette
-** Returns : (void)
-** The result is stored in gfxr_visual_map, gfxr_priority_map, and gfxr_control_map.
-** The palette entry of gfxr_visual_map is never used.
-** Note that the picture will not be drawn dithered; use gfxr_dither_pic0 for that.
-*/
-
+/**
+ * Removes artifacts from a scaled pic.
+ *
+ * Using information from the (correctly rendered) src pic, this function
+ * implements some heuristics to remove artifacts from dest. Must be used
+ * before dither_pic0 is called, because it operates on the index buffer.
+ *
+ * @param[in] dest The scaled pic
+ * @param[in] src An unscaled pic
+ */
void gfxr_remove_artifacts_pic0(gfxr_pic_t *dest, gfxr_pic_t *src);
-/* Removes artifacts from a scaled pic
-** Parameters: (gfxr_pic_t *) dest: The scaled pic
-** (gfxr_pic_t *) src: An unscaled pic
-** Returns : (void)
-** Using information from the (correctly rendered) src pic, this function implements
-** some heuristics to remove artifacts from dest. Must be used before dither_pic0 is
-** called, because it operates on the index buffer.
-*/
+/**
+ * Dithers a gfxr_visual_map.
+ *
+ * @param[in] pic The pic to dither
+ * @param[in] mode One of GFXR_DITHER_MODE
+ * @param[in] pattern One of GFXR_DITHER_PATTERN
+ */
void gfxr_dither_pic0(gfxr_pic_t *pic, int mode, int pattern);
-/* Dithers a gfxr_visual_map
-** Parameters: (gfxr_pic_t *) pic: The pic to dither
-** (int) mode: One of GFXR_DITHER_MODE
-** (int) pattern: One of GFXR_DITHER_PATTERN
-** Returns : (void)
-*/
+/**
+ * Calculates a SCI0 view.
+ *
+ * @param[in] id Resource ID of the view
+ * @param[in] resource Pointer to the resource to read
+ * @param[in] size Size of the resource
+ * @param[in] palette The palette to use
+ * @return The resulting view
+ */
gfxr_view_t *gfxr_draw_view0(int id, byte *resource, int size, int palette);
-/* Calculates an SCI0 view
-** Parameters: (int) id: Resource ID of the view
-** (byte *) resource: Pointer to the resource to read
-** (int) size: Size of the resource
-** (int) palette: The palette to use
-** Returns : (gfxr_view_t *) The resulting view
-*/
-gfx_pixmap_t *gfxr_draw_cursor(int id, byte *resource, int size, bool isSci01);
-/* Calculates n SCI cursor
-** Parameters: (int) id: The cursor's resource ID
-** (byte *) resource: Pointer to the resource data
-** (int) size: Resource size
-** (bool) isSci01: Set to true to load a SCI1 cursor
-** Returns : (gfx_pixmap_t *) A newly allocated pixmap containing an index
-** color representation of the cursor
-*/
+/**
+ * Calculates a SCI cursor.
+ *
+ * @param[in] id The cursor's resource ID
+ * @param[in] resource Pointer to the resource data
+ * @param[in] size Resource size
+ * @param[in] isSci01 Set to true to load a SCI1 cursor
+ * @return A newly allocated pixmap containing an index color
+ * representation of the cursor
+ */
+gfx_pixmap_t *gfxr_draw_cursor(int id, byte *resource, int size,
+ bool isSci01);
+/** @} */
-/*********************/
-/* SCI1 operations */
-/*********************/
+/** @name SCI1/1.1 resource picture operations */
+/** @{ */
+
+/**
+ * Reads an SCI1 palette.
+ *
+ * @param[in] id Resource ID for the palette (or the view it was
+ * found in)
+ * @param[in] resource Source data
+ * @param[in] size Size of the memory block pointed to by resource
+ * @return Palette with the colors
+ */
Palette *gfxr_read_pal1(int id, byte *resource, int size);
-/* Reads an SCI1 palette
-** Parameters: (int) id: Resource ID for the palette (or the view it was found in)
-** (int *) colors_nr: Pointer to the variable the number of colors
-** will be stored in
-** (byte *) resource: Source data
-** (int) size: Size of the memory block pointed to by resource
-** Returns : (Palette *) *colors_nr Palette with the colors
-*/
+/**
+ * Reads an SCI1 palette.
+ *
+ * @param[in] file Palette file
+ * @return Palette with the colors
+ */
Palette *gfxr_read_pal1_amiga(Common::File &file);
-/* Reads an SCI1 palette
-** Parameters: (int *) colors_nr: Pointer to the variable the number of colors
-** will be stored in
-** (FILE *) f: Palette file
-** Returns : (Palette *) Palette with the colors
-*/
+/**
+ * Reads an SCI1.1 palette.
+ *
+ * @param[in] id Resource ID for the palette (or the view it was
+ * found in)
+ * @param[in] resource Source data
+ * @param[in] size Size of the memory block pointed to by resource
+ * @return Palette with the colors
+ */
Palette *gfxr_read_pal11(int id, byte *resource, int size);
-/* Reads an SCI1.1 palette
-** Parameters: (int) id: Resource ID for the palette (or the view it was found in)
-** (int *) colors_nr: Pointer to the variable the number of colors
-** will be stored in
-** (byte *) resource: Source data
-** (int) size: Size of the memory block pointed to by resource
-** Returns : (Palette *) Palette with the colors
-*/
+/**
+ * Calculates an SCI1 view.
+ *
+ * @param[in] id Resource ID of the view
+ * @param[in] resource Pointer to the resource to read
+ * @param[in] size Size of the resource
+ * @param[in] static_pal The static palette
+ * @param[in] isSci11 true if SCI1.1, false otherwise
+ * @return The resulting view
+ */
gfxr_view_t *gfxr_draw_view1(int id, byte *resource, int size, Palette *static_pal, bool isSci11);
-/* Calculates an SCI1 view
-** Parameters: (int) id: Resource ID of the view
-** (byte *) resource: Pointer to the resource to read
-** (int) size: Size of the resource
-** (Palette *) static_pal: The static palette
-** (int) static_pal_nr: Number of entries in static palette
-** Returns : (gfxr_view_t *) The resulting view
-*/
gfx_pixmap_t *gfxr_draw_cel1(int id, int loop, int cel, int mirrored, byte *resource, byte *cel_base, int size, gfxr_view_t *view, bool isAmiga, bool isSci11);
+/** @} */
-
} // End of namespace Sci
#endif // SCI_GFX_GFX_RESOURCE_H
Modified: scummvm/trunk/engines/sci/gfx/gfx_state_internal.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_state_internal.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_state_internal.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -34,14 +34,16 @@
namespace Sci {
-#define GFXW_FLAG_VISIBLE (1<<0)
-#define GFXW_FLAG_OPAQUE (1<<1)
-#define GFXW_FLAG_CONTAINER (1<<2)
-#define GFXW_FLAG_DIRTY (1<<3)
-#define GFXW_FLAG_TAGGED (1<<4)
-#define GFXW_FLAG_MULTI_ID (1<<5) /**< Means that the ID used herein may be used more than once, i.e. is not unique */
-#define GFXW_FLAG_IMMUNE_TO_SNAPSHOTS (1<<6) /**< Snapshot restoring doesn't kill this widget, and +5 bonus to saving throws vs. Death Magic */
-#define GFXW_FLAG_NO_IMPLICIT_SWITCH (1<<7) /**< Ports: Don't implicitly switch to this port when disposing windows */
+enum gfxw_flag_t {
+ GFXW_FLAG_VISIBLE = (1<<0),
+ GFXW_FLAG_OPAQUE = (1<<1),
+ GFXW_FLAG_CONTAINER = (1<<2),
+ GFXW_FLAG_DIRTY = (1<<3),
+ GFXW_FLAG_TAGGED = (1<<4),
+ GFXW_FLAG_MULTI_ID = (1<<5), /**< Means that the ID used herein may be used more than once, i.e. is not unique */
+ GFXW_FLAG_IMMUNE_TO_SNAPSHOTS = (1<<6), /**< Snapshot restoring doesn't kill this widget, and +5 bonus to saving throws vs. Death Magic */
+ GFXW_FLAG_NO_IMPLICIT_SWITCH = (1<<7) /**< Ports: Don't implicitly switch to this port when disposing windows */
+};
struct gfxw_snapshot_t {
int serial; /**< The first serial number to kill */
@@ -82,6 +84,7 @@
typedef int gfxw_bin_op(GfxWidget *, GfxWidget *);
+/** SCI graphics widget */
struct GfxWidget {
public:
int _magic; /**< Extra check after typecasting */
@@ -101,27 +104,28 @@
/**
* The widget automatically removes itself from its owner, if it has one.
- * Deleting a container will recursively free all of its
- * contents.
+ * Deleting a container will recursively free all of its contents.
*/
virtual ~GfxWidget();
/**
* Draws the widget.
*
- * The widget is drawn iff it is flagged as dirty. Invoking this operation on
- * a container widget will recursively draw all of its contents.
+ * The widget is drawn iff it is flagged as dirty. Invoking this operation
+ * on a container widget will recursively draw all of its contents.
*
- * @param pos The position to draw to (added to the widget's internal position)
+ * @param[in] pos The position to draw to (added to the widget's
+ * internal position)
*/
virtual int draw(const Common::Point &pos) = 0;
/**
* Tags the specified widget.
*
- * If invoked on a container widget, this will also tag all of the container's
- * contents (but not the contents' contents!)
- * FIXME: Actually, the code in GfxContainer::tag contradicts the last claim!
+ * If invoked on a container widget, this will also tag all of the
+ * container's contents (but not the contents' contents!)
+ * FIXME: Actually, the code in GfxContainer::tag contradicts the last
+ * claim!
*/
virtual void tag() {
_flags |= GFXW_FLAG_TAGGED;
@@ -130,10 +134,10 @@
/**
* Prints a string representation of the widget with sciprintf.
*
- * Will recursively print all of the widget's contents if the widget contains
- * further sub-widgets
+ * Will recursively print all of the widget's contents if the widget
+ * contains further sub-widgets
*
- * @param indentation Number of double spaces to indent
+ * @param[in] indentation Number of double spaces to indent
*/
virtual void print(int indentation) const;
@@ -143,55 +147,63 @@
* This comparison only applies to some widgets; compare_to(a,a)=0 is not
* guaranteed. It may be used for sorting for all widgets.
*
- * @param other other widget
- * @return <0, 0, or >0 if other is, respectively, less than, equal
- * to, or greater than self
+ * @param other The other widget
+ * @return <0, 0, or >0 if other is, respectively, less than, equal
+ * to, or greater than self
*/
gfxw_bin_op *compare_to;
/**
* Compares two compareable widgets for equality.
*
- * This operation checks whether two widgets describe the same graphical data.
- * It is used to determine whether a new widget should be discarded because it
- * describes the same graphical data as an old widget that has already been
- * drawn. For lists, it also checks whether all contents are in an identical
- * order.
+ * This operation checks whether two widgets describe the same graphical
+ * data. It is used to determine whether a new widget should be discarded
+ * because it describes the same graphical data as an old widget that has
+ * already been drawn. For lists, it also checks whether all contents are
+ * in an identical order.
*
- * @param other other widget
- * @return false if the widgets are not equal, true if they match
+ * @param[in] other The other widget
+ * @return false if the widgets are not equal, true if they match
*/
gfxw_bin_op *equals;
/**
- * Determine whether other should replace this even though they are equivalent.
+ * Determine whether other should replace this even though they are
+ * equivalent.
*
* When 'equals' returns true, this means that no new widget will be added.
* However, in some cases newer widgets may contain information that should
- * cause the older widget to be removed nonetheless; this is indicated by this
- * function.
+ * cause the older widget to be removed nonetheless; this is indicated by
+ * this function.
*
- * @param other other widget
- * @return false if this should be kept, true if this should be replaced by the 'other'
+ * @param[in] other The other widget
+ * @return false if this should be kept, true if this should be
+ * replaced by the 'other'
*/
gfxw_bin_op *should_replace;
/**
- * Tests whether drawing this after other would reduce all traces of other.
+ * Tests whether drawing this after other would reduce all traces of
+ * other.
*
- * /a superarea_of b <=> for each pixel of b there exists an opaque pixel in a at the same location
+ * /a superarea_of b <=> for each pixel of b there exists an opaque pixel
+ * in a at the same location
*
- * @param other the widget to compare for containment
- * @return true if this is superarea_of other, false otherwise
+ * @param[in] other The widget to compare for containment
+ * @return true if this is superarea_of other, false otherwise
*/
gfxw_bin_op *superarea_of;
/**
* Sets the visual for the widget
- * This function is called by container->add() and need not be invoked explicitly.
- * It also makes sure that dirty rectangles are passed to parent containers.
+ *
+ * This function is called by container->add() and need not be invoked
+ * explicitly. It also makes sure that dirty rectangles are passed to
+ * parent containers.
+ *
+ * @param[in] visual GfxVisual to set for the widget
*/
- virtual int setVisual(GfxVisual *);
+ virtual int setVisual(GfxVisual *visual);
//protected:
void printIntern(int indentation) const;
@@ -200,6 +212,7 @@
#define GFXW_IS_BOX(widget) ((widget)->_type == GFXW_BOX)
+/** SCI box widget */
struct GfxBox : public GfxWidget {
gfx_color_t _color1, _color2;
gfx_box_shade_t _shadeType;
@@ -213,6 +226,7 @@
#define GFXW_IS_PRIMITIVE(widget) ((widget)->_type == GFXW_RECT || (widget)->_type == GFXW_LINE)
+/** SCI graphics primitive */
struct GfxPrimitive : public GfxWidget {
gfx_color_t _color;
gfx_line_mode_t _lineMode;
@@ -227,6 +241,7 @@
#define GFXW_IS_VIEW(widget) ((widget)->_type == GFXW_VIEW || (widget)->_type == GFXW_STATIC_VIEW \
|| (widget)->_type == GFXW_DYN_VIEW || (widget)->_type == GFXW_PIC_VIEW)
+/** SCI graphics view */
struct GfxView : public GfxWidget {
Common::Point _pos; /**< Implies the value of 'bounds' in GfxWidget */
gfx_color_t _color;
@@ -242,6 +257,7 @@
};
#define GFXW_IS_DYN_VIEW(widget) ((widget)->_type == GFXW_DYN_VIEW || (widget)->_type == GFXW_PIC_VIEW)
+/** SCI dynamic view */
struct GfxDynView : public GfxView {
/* FIXME: This code is specific to SCI */
rect_t draw_bounds; /* The correct position to draw to */
@@ -265,6 +281,7 @@
#define GFXW_IS_TEXT(widget) ((widget)->_type == GFXW_TEXT)
+/** SCI text widget */
struct GfxText : public GfxWidget {
int _font;
int lines_nr, lineheight, lastline_width;
@@ -293,7 +310,7 @@
typedef int gfxw_container_op(GfxContainer *, GfxWidget *);
typedef int gfxw_rect_op(GfxContainer *, rect_t, int);
-
+/** SCI container widget */
struct GfxContainer : public GfxWidget {
rect_t zone; /**< The writeable zone (absolute) for contained objects */
DirtyRectList _dirtyRects; /**< List of dirty rectangles */
@@ -324,7 +341,7 @@
#define GFXW_IS_LIST(widget) ((widget)->_type == GFXW_LIST || (widget)->_type == GFXW_SORTED_LIST)
#define GFXW_IS_SORTED_LIST(widget) ((widget)->_type == GFXW_SORTED_LIST)
-
+/** SCI graphics list */
struct GfxList : public GfxContainer {
public:
GfxList(rect_t area, bool sorted);
@@ -334,6 +351,7 @@
};
#define GFXW_IS_VISUAL(widget) ((widget)->_type == GFXW_VISUAL)
+/** SCI graphic visual */
struct GfxVisual : public GfxContainer {
Common::Array<GfxPort *> _portRefs; /**< References to ports */
int _font; /**< Default font */
@@ -353,6 +371,7 @@
};
#define GFXW_IS_PORT(widget) ((widget)->_type == GFXW_PORT)
+/** SCI graphics port */
struct GfxPort : public GfxContainer {
GfxList *_decorations; /**< optional window decorations - drawn before the contents */
GfxWidget *port_bg; /**< Port background widget or NULL */
@@ -366,16 +385,20 @@
byte gray_text; /**< Whether text is 'grayed out' (dithered) */
public:
- /* Creates a new port widget with the default settings
- ** Paramaters: (GfxVisual *) visual: The visual the port is added to
- ** (GfxPort *) predecessor: The port's predecessor
- ** (rect_t) area: The screen area covered by the port (absolute position)
- ** (gfx_color_t) fgcolor: Foreground drawing color
- ** (gfx_color_t) bgcolor: Background color
- ** A port differentiates itself from a list in that it contains additional information,
- ** and an optional title (stored in a display list).
- ** Ports are assigned implicit IDs identifying their position within the port stack.
- */
+ /**
+ * Creates a new port widget with the default settings
+ *
+ * A port differentiates itself from a list in that it contains additional
+ * information, and an optional title (stored in a display list).
+ * Ports are assigned implicit IDs identifying their position within the
+ * port stack.
+ *
+ * @param[in] visual The visual the port is added to
+ * @param[in] area The screen area covered by the port (absolute
+ * position)
+ * @param[in] fgcolor Foreground drawing color
+ * @param[in] bgcolor Background color
+ */
GfxPort(GfxVisual *visual, rect_t area, gfx_color_t fgcolor, gfx_color_t bgcolor);
~GfxPort();
Modified: scummvm/trunk/engines/sci/gfx/gfx_system.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_system.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_system.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -36,7 +36,7 @@
#define GFX_DEBUG
/* General output macros */
-# define GFXERROR sciprintf("GFX Error: %s, L%d:", __FILE__, __LINE__); error
+#define GFXERROR sciprintf("GFX Error: %s, L%d:", __FILE__, __LINE__); error
/***********************/
/*** Data structures ***/
@@ -50,32 +50,35 @@
** enabled */
#define GFX_MODE_FLAG_REVERSE_ALPHA (1<<1)
-/** Graphics mode description */
+/** Graphics mode description
+ *
+ * Color masks:
+ * Each of the mask/shift pairs describe where the corresponding color
+ * values are stored for the described mode. Internally, color
+ * calculations are done by using 32 bit values for r, g, b, a. After
+ * the internal values have been calculated, they are shifted RIGHT
+ * by the xxx_shift amount described above, then ANDed with the
+ * corresponding color mask; finally, all three results are ORred to-
+ * gether. The alpha values are used as appropriate; if alpha_mask is
+ * zero, then images use a special alpha map.
+ */
+
struct gfx_mode_t {
- int xfact, yfact; /* Horizontal and vertical scaling factors */
- int xsize, ysize; /* Horizontal and vertical size */
- int bytespp; /* Bytes per pixel */
+ int xfact, yfact; /**< Horizontal and vertical scaling factors */
+ int xsize, ysize; /**< Horizontal and vertical size */
+ int bytespp; /**< Bytes per pixel */
- uint32 flags; /* GFX_MODE_FLAG_* Flags- see above */
+ uint32 flags; /**< GFX_MODE_FLAG_* Flags- see above */
+ /**
+ * Palette or NULL to indicate non-palette mode.
+ * Palette mode is only supported for bytespp = 1
+ */
+ Palette *palette;
- Palette *palette; // Palette or NULL to indicate non-palette mode.
- // Palette mode is only supported for bytespp = 1
-
- /* Color masks */
uint32 red_mask, green_mask, blue_mask, alpha_mask;
short red_shift, green_shift, blue_shift, alpha_shift;
-
- /* Each of the mask/shift pairs describe where the corresponding color
- ** values are stored for the described mode. Internally, color
- ** calculations are done by using 32 bit values for r, g, b, a. After
- ** the internal values have been calculated, they are shifted RIGHT
- ** by the xxx_shift amount described above, then ANDed with the
- ** corresponding color mask; finally, all three results are ORred to-
- ** gether. The alpha values are used as appropriate; if alpha_mask is
- ** zero, then images use a special alpha map. */
-
};
@@ -84,16 +87,16 @@
/** Pixmap-specific color entries */
struct gfx_pixmap_color_t{
- int global_index; /* Global index color or GFX_COLOR_INDEX_UNMAPPED. */
- uint8 r, g, b; /* Real color */
+ int global_index; /**< Global index color or GFX_COLOR_INDEX_UNMAPPED. */
+ uint8 r, g, b; /**< Real color */
};
/** Full color */
struct gfx_color_t {
PaletteEntry visual;
- uint8 alpha; /* transparency = (1-opacity) */
+ uint8 alpha; /**< transparency = (1-opacity) */
int8 priority, control;
- byte mask; /* see mask values below */
+ byte mask; /**< see mask values below */
};
@@ -104,11 +107,15 @@
int width, height; /* width, height: (x,y,width,height)=(5,5,1,1) occupies 1 pixel */
};
-/* Generates a rect_t from index data
-** Parameters: (int x int) x,y: Upper left point of the rectangle
-** (int x int) width, height: Horizontal and vertical extension of the rectangle
-** Returns : (rect_t) A rectangle matching the supplied parameters
-*/
+/**
+ * Generates a rect_t from index data
+ *
+ * @param[in] x Left side of the rectangle
+ * @param[in] y Top side of the rectangle
+ * @param[in] width Horizontal extent of the rectangle
+ * @param[in] height Verical extent of the rectangle
+ * @return A rectangle matching the supplied parameters
+ */
static inline rect_t gfx_rect(int x, int y, int width, int height) {
rect_t rect;
@@ -120,11 +127,16 @@
return rect;
}
-// Temporary helper functions to ease the transition from rect_t to Common::Rect
+/**
+ * Temporary helper function to ease the transition from rect_t to Common::Rect
+ */
static inline rect_t toSCIRect(Common::Rect in) {
return gfx_rect(in.left, in.top, in.width(), in.height());
}
+/**
+ * Temporary helper function to ease the transition from rect_t to Common::Rect
+ */
static inline Common::Rect toCommonRect(rect_t in) {
return Common::Rect(in.x, in.y, in.x + in.width, in.y + in.height);
}
@@ -133,10 +145,13 @@
#define OVERLAP(a, b, z, zl) (a.z >= b.z && a.z < (b.z + b.zl))
-/* Determines whether two rects overlap
-** Parameters: (rect_t x rect_t) a,b: The two rect_ts to check for overlap
-** Returns : (int) 1 if they overlap, 0 otherwise
-*/
+/**
+ * Determines whether two rects overlap
+ *
+ * @param[in] a First rect to check for overlap
+ * @param[in] b Second rect to check for overlap
+ * @return 1 if they overlap, 0 otherwise
+ */
static inline int gfx_rects_overlap(rect_t a, rect_t b) {
return (OVERLAP(a, b, x, width) || OVERLAP(b, a, x, width)) && (OVERLAP(a, b, y, height) || OVERLAP(b, a, y, height));
}
@@ -150,86 +165,95 @@
#define GFX_PIC_COLORS 256
-#define GFX_PIXMAP_FLAG_SCALED_INDEX (1<<0) /* Index data is scaled already */
-#define GFX_PIXMAP_FLAG_INSTALLED (1<<2) /* Pixmap has been registered */
-#define GFX_PIXMAP_FLAG_PALETTIZED (1<<6) /* Indicates a palettized view */
+#define GFX_PIXMAP_FLAG_SCALED_INDEX (1<<0) /* Index data is scaled already */
+#define GFX_PIXMAP_FLAG_INSTALLED (1<<2) /* Pixmap has been registered */
+#define GFX_PIXMAP_FLAG_PALETTIZED (1<<6) /* Indicates a palettized view */
#define GFX_PIXMAP_COLOR_KEY_NONE -1 /* No transpacency colour key */
#define GFX_CURSOR_TRANSPARENT 255 // Cursor colour key
-struct gfx_pixmap_t { /* gfx_pixmap_t: Pixel map */
+/** Pixel map */
+struct gfx_pixmap_t {
- /*** Meta information ***/
- int ID; /* Resource ID, or GFX_RESID_NONE for anonymous graphical data */
- short loop, cel; /* loop and cel number for views */
+ /** @name Meta information
+ * @{*/
+ int ID; /**< Resource ID, or GFX_RESID_NONE for anonymous graphical data */
+ short loop; /**< loop number for view */
+ short cel; /**< cel number for view */
+ /** @}*/
+ /** @name Color map
+ * @{*/
+ Palette *palette;
- /*** Color map ***/
- Palette *palette;
+ /**
+ * color entries, or NULL if the default palette is to be used. A maximum
+ * of 255 colors is allowed; color index 0xff is reserved for transparency.
+ * As a special exception, 256 colors are allowed for background pictures
+ * (which do not use transparency)
+ */
int colors_nr() const { return palette ? palette->size() : 0; }
- /* color entries, or NULL if the
- ** default palette is to be used.
- ** A maximum of 255 colors is allowed; color
- ** index 0xff is reserved for transparency.
- ** As a special exception, 256 colors are
- ** allowed for background pictures (which do
- ** not use transparency)
- */
+
uint32 flags;
+ /* @} */
- /*** Hot spot ***/
- int xoffset, yoffset; /* x and y coordinates of the 'hot spot' (unscaled) */
+ /** @name Hot spot
+ * x and y coordinates of the 'hot spot' (unscaled)
+ * @{*/
+ int xoffset, yoffset;
+ /** @} */
- /*** Index data ***/
- int index_width, index_height; /* width and height of the indexed original image */
- byte *index_data; /* Color-index data, or NULL if read from an
- ** external source
- */
+ /** @name Index data
+ * @{
+ */
+ int index_width; /**< width of the indexed original image */
+ int index_height; /**< height of the indexed original image */
+ byte *index_data; /**< Color-index data, or NULL if read from an external source */
+ /** @} */
- /*** Drawable data ***/
- int width, height; /* width and height of the actual image */
- int data_size; /* Amount of allocated memory */
- byte *data; /* Drawable data, or NULL if not converted. */
+ /** @name Drawable data
+ * @{
+ */
+ int width; /**< width of the actual image */
+ int height; /**< height of the actual image */
+ int data_size; /**< Amount of allocated memory */
+ byte *data; /**< Drawable data, or NULL if not converted. */
- byte *alpha_map; /* Byte map with alpha values. It is used only if the
- ** graphics mode's alpha_mask is zero.
- */
+ byte *alpha_map; /**< Byte map with alpha values. It is used only if the graphics mode's alpha_mask is zero. */
- int color_key;
- int palette_revision; // Revision of palette at the time data was generated
+ int color_key; /**< The color to make transparent */
+ int palette_revision; /**< Revision of palette at the time data was generated */
+ /** @} */
};
-/***********************/
-/*** Constant values ***/
-/***********************/
-/* Return values */
+/** @name Constant values
+ * @{ */
+
+/** Return values */
enum gfx_return_value_t {
- GFX_OK = 0, /* Indicates "operation successful" */
- GFX_ERROR = -1, /* Indicates "operation failed" */
- GFX_FATAL = -2
- /* Fatal error: Used by graphics drivers to indicate that they were unable to
- ** do anything useful
- */
+ GFX_OK = 0, /**< Indicates "operation successful" */
+ GFX_ERROR = -1, /**< Indicates "operation failed" */
+ GFX_FATAL = -2 /**< Fatal error: Used by graphics drivers to indicate
+ that they were unable to do anything useful */
};
-
-enum gfx_map_mask_t {/* Map masks */
+/** Map masks */
+enum gfx_map_mask_t {
GFX_MASK_NONE = 0,
GFX_MASK_VISUAL = 1,
GFX_MASK_PRIORITY = 2,
GFX_MASK_CONTROL = 4
};
-/* 'no priority' mode */
+/** 'no priority' mode */
enum {
GFX_NO_PRIORITY = -1
};
-/* Text alignment values */
-
+/** Text alignment values */
enum gfx_alignment_t {
ALIGN_RIGHT = -1,
ALIGN_TOP = -1,
@@ -240,16 +264,16 @@
enum gfx_line_mode_t {
- GFX_LINE_MODE_CORRECT, /* Scaled separately */
- GFX_LINE_MODE_FAST, /* Scaled by (xfact+yfact)/2 */
- GFX_LINE_MODE_FINE /* Always drawn at width 1 */
+ GFX_LINE_MODE_CORRECT, /**< Scaled separately */
+ GFX_LINE_MODE_FAST, /**< Scaled by (xfact+yfact)/2 */
+ GFX_LINE_MODE_FINE /**< Always drawn at width 1 */
};
enum gfx_brush_mode_t {
- GFX_BRUSH_MODE_SCALED, /* Just scale the brush pixels */
- GFX_BRUSH_MODE_ELLIPSES, /* Replace pixels with ellipses */
- GFX_BRUSH_MODE_RANDOM_ELLIPSES, /* Replace pixels with ellipses moved and re-scaled randomly */
- GFX_BRUSH_MODE_MORERANDOM /* Distribute randomly */
+ GFX_BRUSH_MODE_SCALED, /**< Just scale the brush pixels */
+ GFX_BRUSH_MODE_ELLIPSES, /**< Replace pixels with ellipses */
+ GFX_BRUSH_MODE_RANDOM_ELLIPSES, /**< Replace pixels with ellipses moved and re-scaled randomly */
+ GFX_BRUSH_MODE_MORERANDOM /**< Distribute randomly */
};
@@ -260,18 +284,19 @@
enum gfx_rectangle_fill_t {
- GFX_SHADE_FLAT, /* Don't shade */
- GFX_SHADE_VERTICALLY, /* Shade vertically */
- GFX_SHADE_HORIZONTALLY /* Shade horizontally */
+ GFX_SHADE_FLAT, /**< Don't shade */
+ GFX_SHADE_VERTICALLY, /**< Shade vertically */
+ GFX_SHADE_HORIZONTALLY /**< Shade horizontally */
};
enum gfx_color_mode_t {
- GFX_COLOR_MODE_AUTO = 0, /* Auto-detect- handled by the gfxop library */
- GFX_COLOR_MODE_INDEX = 1, /* Index mode */
- GFX_COLOR_MODE_HIGH = 2, /* High color mode (15bpp or 16 bpp) */
- GFX_COLOR_MODE_TRUE = 4 /* True color mode (24 bpp padded to 32 bpp) */
+ GFX_COLOR_MODE_AUTO = 0, /**< Auto-detect- handled by the gfxop library */
+ GFX_COLOR_MODE_INDEX = 1, /**< Index mode */
+ GFX_COLOR_MODE_HIGH = 2, /**< High color mode (15bpp or 16 bpp) */
+ GFX_COLOR_MODE_TRUE = 4 /**< True color mode (24 bpp padded to 32 bpp) */
};
+/** @} */
} // End of namespace Sci
Modified: scummvm/trunk/engines/sci/gfx/gfx_tools.h
===================================================================
--- scummvm/trunk/engines/sci/gfx/gfx_tools.h 2009-06-22 20:52:08 UTC (rev 41784)
+++ scummvm/trunk/engines/sci/gfx/gfx_tools.h 2009-06-22 21:48:47 UTC (rev 41785)
@@ -23,9 +23,6 @@
*
*/
-/* SCI graphics subsystem helper functions */
-
-
#ifndef SCI_GFX_GFX_TOOLS_H
#define SCI_GFX_GFX_TOOLS_H
@@ -36,162 +33,198 @@
namespace Sci {
+/** @name SCI graphics subsystem helper functions */
+/** @{ */
+
enum gfx_xlate_filter_t {
GFX_XLATE_FILTER_NONE,
GFX_XLATE_FILTER_LINEAR,
GFX_XLATE_FILTER_TRILINEAR
};
+/**
+ * Allocates a new gfx_mode_t structure with the specified parameters
+ *
+ * @param[in] xfact Horizontal scaling factors
+ * @param[in] yfact Vertical scaling factors
+ * @param[in] format Pixel format description
+ * @param[in] palette Number of palette colors, 0 if we're not in palette mode
+ * @param[in] flags GFX_MODE_FLAG_* values ORred together, or just 0
+ * @return A newly allocated gfx_mode_t structure
+ */
gfx_mode_t *gfx_new_mode(int xfact, int yfact, const Graphics::PixelFormat &format, Palette *palette, int flags);
-/* Allocates a new gfx_mode_t structure with the specified parameters
-** Parameters: (int x int) xfact x yfact: Horizontal and vertical scaling factors
-** (Graphics::PixelFormat) format: pixel format description
-** (int) palette: Number of palette colors, 0 if we're not in palette mode
-** (int) flags: GFX_MODE_FLAG_* values ORred together, or just 0
-** Returns : (gfx_mode_t *) A newly allocated gfx_mode_t structure
-*/
-
+/**
+ * Clips a rect_t
+ *
+ * @param[in] box Pointer to the box to clip
+ * @param[in] maxx Maximum allowed width
+ * @param[in] maxy Maximum allowed height
+ */
void gfx_clip_box_basic(rect_t *box, int maxx, int maxy);
-/* Clips a rect_t
-** Parameters: (rect_t *) box: Pointer to the box to clip
-** (int x int) maxx, maxy: Maximum allowed width and height
-** Returns : (void)
-*/
-
+/**
+ * Frees all memory allocated by a mode structure
+ * @param[in] mode The mode to free
+ */
void gfx_free_mode(gfx_mode_t *mode);
-/* Frees all memory allocated by a mode structure
-** Parameters: (gfx_mode_t *) mode: The mode to free
-** Returns : (void)
-*/
-
+/**
+ * Creates a new pixmap structure
+ *
+ * The following fiels are initialized:
+ * ID, loop, cel, index_width, index_height, xl, yl, data <- NULL,
+ * alpha_map <- NULL, internal.handle <- 0, internal.info <- NULL,
+ * colors <- NULL, index_scaled <- 0
+ *
+ * @param[in] xl Width (in SCI coordinates) of the pixmap
+ * @param[in] yl Height (in SCI coordinates) of the pixmap
+ * @param[in] resid The pixmap's resource ID, or GFX_RESID_NONE
+ * @param[in] loop For views: The pixmap's loop number
+ * @param[in] cel For cels: The pixmap's cel number
+ * @return The newly allocated pixmap
+ */
gfx_pixmap_t *gfx_new_pixmap(int xl, int yl, int resid, int loop, int cel);
-/* Creates a new pixmap structure
-** Parameters: (int x int) xl x yl: The dimensions (in SCI coordinates) of the pixmap
-** (int) resid: The pixmap's resource ID, or GFX_RESID_NONE
-** (int) loop: For views: The pixmap's loop number
-** (int) cel: For cels: The pixmap's cel number
-** Returns : (gfx_pixmap_t *) The newly allocated pixmap
-** The following fiels are initialized:
-** ID, loop, cel, index_width, index_height, xl, yl, data <- NULL,
-** alpha_map <- NULL, internal.handle <- 0, internal.info <- NULL, colors <- NULL,
-** index_scaled <- 0
-*/
+/**
+ * Clones a pixmap, minus its index data, palette and driver-specific
+ * handles
+ *
+ * @param[in] pixmap The pixmap to clone
+ * @param[in] mode The mode to be applied to the pixmap
+ * @return The clone
+ */
gfx_pixmap_t *gfx_clone_pixmap(gfx_pixmap_t *pixmap, gfx_mode_t *mode);
-/* Clones a pixmap, minus its index data, palette and driver-specific handles
-** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to clone
-** (gfx_mode_t *) mode: The mode to be applied to the pixmap
-** Returns : (gfx_pixmap_t *) The clone
-*/
-
+/**
+ * Allocates the index_data field of a pixmap
+ *
+ * @param[in] pixmap The pixmap to allocate for
+ * @return The pixmap
+ */
gfx_pixmap_t *gfx_pixmap_alloc_index_data(gfx_pixmap_t *pixmap);
-/* Allocates the index_data field of a pixmap
-** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to allocate for
-** Returns : (gfx_pixmap_t *) pixmap
-*/
+/**
+ * Frees the index_data field of a pixmap
+ *
+ * @param[in] pixmap The pixmap to modify
+ * @return The pixmap
+ */
gfx_pixmap_t *gfx_pixmap_free_index_data(gfx_pixmap_t *pixmap);
-/* Frees the index_data field of a pixmap
-** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to modify
-** Returns : (gfx_pixmap_t *) pixmap
-*/
+/**
+ * Allocates the data field of a pixmap
+ *
+ * @param[in] pixmap The pixmap to allocate for
+ * @param[in] mode The mode the memory is to be allocated for
+ * @return The pixmap
+ */
gfx_pixmap_t *gfx_pixmap_alloc_data(gfx_pixmap_t *pixmap, gfx_mode_t *mode);
-/* Allocates the data field of a pixmap
-** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to allocate for
-** (gfx_mode_t *) mode: The mode the memory is to be allocated for
-** Returns : (gfx_pixmap_t *) pixmap
-*/
+/**
+ * Frees the memory allocated for a pixmap's data field
+ *
+ * @param[in] pixmap The pixmap to modify
+ * @return The pixmap
+ */
gfx_pixmap_t *gfx_pixmap_free_data(gfx_pixmap_t *pixmap);
-/* Frees the memory allocated for a pixmap's data field
-** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to modify
-** Returns : (gfx_pixmap_t *) pixmap
-*/
+/**
+ * Frees all memory associated with a pixmap
+ *
+ * @param[in] pxm The pixmap to free
+ */
void gfx_free_pixmap(gfx_pixmap_t *pxm);
-/* Frees all memory associated with a pixmap
-** Parameters: (gfx_pixmap_t *) pxm: The pixmap to free
-** Returns : (void)
-*/
-void gfx_draw_line_pixmap_i(gfx_pixmap_t *pxm, Common::Point start, Common::Point end, int color);
-/* Draws a line to a pixmap's index data buffer
-** Parameters: (gfx_pixmap_t *) pxm: The pixmap to draw to
@@ Diff output truncated at 100000 characters. @@
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Scummvm-git-logs
mailing list