Ticket #9029: 0001-SCI-Convert-gfx-subsystem-headers-to-Doxygen-format.patch

File 0001-SCI-Convert-gfx-subsystem-headers-to-Doxygen-format.patch, 185.4 KB (added by SF/lwalkera, 10 years ago)

The patch

  • engines/sci/gfx/font.h

    From 61b390ede2c754723eb8c36db1b2a96d090125e6 Mon Sep 17 00:00:00 2001
    From: Laine Walker-Avina <lwalkera@ieee.org>
    Date: Fri, 19 Jun 2009 14:26:23 -0700
    Subject: [PATCH] SCI: Convert gfx subsystem headers to Doxygen format
    
    ---
     engines/sci/gfx/font.h               |  165 ++++---
     engines/sci/gfx/gfx_driver.h         |  327 +++++++------
     engines/sci/gfx/gfx_gui.h            |  324 +++++++-----
     engines/sci/gfx/gfx_options.h        |   22 +-
     engines/sci/gfx/gfx_res_options.h    |   44 +-
     engines/sci/gfx/gfx_resmgr.h         |  302 +++++++-----
     engines/sci/gfx/gfx_resource.h       |  359 +++++++------
     engines/sci/gfx/gfx_state_internal.h |  141 +++---
     engines/sci/gfx/gfx_system.h         |  233 +++++----
     engines/sci/gfx/gfx_tools.h          |  273 ++++++-----
     engines/sci/gfx/gfx_widgets.h        |  468 ++++++++++-------
     engines/sci/gfx/menubar.h            |   88 ++--
     engines/sci/gfx/operations.h         |  957 +++++++++++++++++++---------------
     engines/sci/gfx/palette.h            |   20 +-
     engines/sci/gfx/res_pic.cpp          |    2 +-
     engines/sci/gfx/seq_decoder.h        |    7 +-
     16 files changed, 2100 insertions(+), 1632 deletions(-)
    
    diff --git a/engines/sci/gfx/font.h b/engines/sci/gfx/font.h
    index 935414f..e4306a8 100644
    a b  
    3030
    3131
    3232namespace Sci {
     33/** @name Font operations and stuctures */
     34/** @{ */
    3335
    3436struct TextFragment {
    3537        const char *offset;
    struct TextFragment {  
    3941        TextFragment(const char *o) : offset(o), length(0) {}
    4042};
    4143
    42 
    43 struct gfx_bitmap_font_t { /* gfx_bitmap_font_t: Bitmap font information */
    44         int ID; /* Unique resource ID */
    45 
    46         int chars_nr; /* Numer of available characters */
    47 
    48         int *widths; /* chars_nr character widths, in pixels */
    49 
    50         int row_size; /* Byte size of each pixel row. For unscaled fonts, this is
    51                       ** always 1, 2, or 4. Otherwise, it's a multiple of 4.
    52                       */
    53 
    54         int line_height; /* Height of each text line (usually identical to height) */
    55         int height; /* Height for all characters, in pixel rows */
    56         int char_size; /* Amount of memory occupied by one character in data */
    57 
    58         byte *data; /* Font data, consisting of 'chars_nr' entries of 'height' rows
    59                     ** of 'row_size' bytes. For each character ch, its first byte
    60                     ** (the topmost row) is located at (data + (charsize * ch)), and
    61                     ** its pixel width is widths[ch], provided that (ch < chars_nr).
    62                     */
    63 
     44/**
     45 * @brief Bitmap font information.
     46 */
     47struct gfx_bitmap_font_t {
     48        int ID;                         /**< Unique resource ID */
     49        int chars_nr;           /**< Numer of available characters */
     50        int *widths;            /**< chars_nr character widths, in pixels */
     51        int row_size;           /**
     52                                                 * Byte size of each pixel row. For unscaled fonts,
     53                                                 * this is always 1, 2, or 4. Otherwise, it's a
     54                                                 * multiple of 4.
     55                                                 */
     56        int line_height;        /**
     57                                                 * Height of each text line (usually identical to
     58                                                 * height)
     59                                                 */
     60        int height;                     /**< Height for all characters, in pixel rows */
     61        int char_size;          /**
     62                                                  * Amount of memory occupied by one character
     63                                                  * in data
     64                                                  */
     65        byte *data;                     /**
     66                                                  * Font data, consisting of 'chars_nr' entries
     67                                                  * of 'height' rows of 'row_size' bytes. For each
     68                                                  * character ch, its first byte (the topmost row)
     69                                                  * is located at (data + (charsize * ch)), and its
     70                                                  * pixel width is widths[ch], provided that
     71                                                  * (ch < chars_nr).
     72                                                  */
    6473};
    6574
    66 /*******************/
    67 /* Font operations */
    68 /*******************/
    69 
    70 /* SCI0, SCI01 and SCI1 all use the same font format. */
     75/**
     76 * @brief Font handling flags.
     77 *
     78 * SCI0, SCI01 and SCI1 all use the same font format.
     79 */
    7180enum fontFlags {
    72         kFontCountWhitespace = 1 << 0,    // In SQ3, whitespace is included in text size
    73         kFontNoNewlines      = 1 << 1,    // Don't treat newline characters
    74         kFontIgnoreLF        = 1 << 2     // Interpret CR LF sequences as a single newline, rather than two
     81        kFontCountWhitespace = 1 << 0,    //!< In SQ3, whitespace is included in text size
     82        kFontNoNewlines      = 1 << 1,    //!< Don't treat newline characters
     83        kFontIgnoreLF        = 1 << 2     //!< Interpret CR LF sequences as a single newline, rather than two
    7584};
    7685
     86/**
     87 * @brief Generates a bitmap font data structure from a resource.
     88 *
     89 * @param[in] id                Resource ID of the resulting font
     90 * @param[in] resource  Pointer to the resource data
     91 * @param[in] size              Size of the resource block
     92 * @return                              The resulting font structure, or NULL on error
     93 */
    7794gfx_bitmap_font_t *gfxr_read_font(int id, byte *resource, int size);
    78 /* Generates a bitmap font data structure from a resource
    79 ** Parameters: (int) id: Resource ID of the resulting font
    80 **             (byte *) resource: Pointer to the resource data
    81 **             (int) size: Size of the resource block
    82 ** Returns   : (gfx_bitmap_font_t *) The resulting font structure, or
    83 **                                   NULL on error
    84 */
    8595
     96/**
     97 * @brief Frees a previously allocated font structure.
     98 *
     99 * @param font  The font to free
     100 */
    86101void gfxr_free_font(gfx_bitmap_font_t *font);
    87 /* Frees a previously allocated font structure
    88 ** Parameters: (gfx_bitmap_font_t *) font: The font to free
    89 ** Returns   : (void)
    90 */
    91102
     103/**
     104 * @brief Calculates the size that would be occupied by drawing a specified
     105 * text.
     106 *
     107 * This function assumes 320x200 mode.
     108 *
     109 * @param[in]  font                     The font to calculate with
     110 * @param[in]  max_width        Maximum pixel width allowed for the output
     111 * @param[in]  text                     The text to calculate for
     112 * @param[in]  flags            Any text formatting flags
     113 * @param[out] fragments        A newly allocated array of text_fragments,
     114 *                                                      containing the start and size of each string
     115 *                                                      segment.
     116 * @param[out] width            The resulting width
     117 * @param[out] height           The resulting height
     118 * @param[out] line_height      Pixel height of a single line of text
     119 * @param[out] last_offset      Pixel offset after the last drawn line
     120 * @return                                      true if successful, false otherwise
     121 */
    92122bool gfxr_font_calculate_size(Common::Array<TextFragment> &fragments,
    93123    gfx_bitmap_font_t *font, int max_width, const char *text,
    94124        int *width, int *height, int *line_height, int *last_offset, int flags);
    95 /* Calculates the size that would be occupied by drawing a specified text
    96 ** Parameters: (gfx_bitmap_font_t *) font: The font to calculate with
    97 **             (int) max_width: Maximum pixel width allowed for the output
    98 **             (const char *) text: The text to calculate for
    99 **             (int) flags: Any text formatting flags
    100 ** Returns   : (text_fragment *) a newly allocated array of text_fragments,
    101 **                               containing the start and size of each string
    102 **                               segment
    103 **             (int) *width: The resulting width
    104 **             (int) *height: The resulting height
    105 **             (int) *line_height: Pixel height of a single line of text
    106 **             (int) *last_offset: Pixel offset after the last drawn line
    107 ** This function assumes 320x200 mode.
    108 */
    109 
    110 gfx_pixmap_t *gfxr_draw_font(gfx_bitmap_font_t *font, const char *text, int characters,
    111         PaletteEntry *fg0, PaletteEntry *fg1, PaletteEntry *bg);
    112 /* Draws text in a specific font to a pixmap
    113 ** Parameters: (gfx_bitmap_font_t *) font: The font to use for drawing
    114 **             (char *) text: The start of the text to draw
    115 **             (int) characters: The number of characters to draw
    116 **             (gfx_pixmap_color_t *) fg0: The first foreground color
    117 **             (gfx_pixmap_color_t *) fg1: The second foreground color
    118 **             (gfx_pixmap_color_t *) bg: The background color
    119 ** Returns   : (gfx_pixmap_t *) The result pixmap, or NULL on error
    120 ** The results are written to the pixmap's index buffer. Contents of the
    121 ** foreground and background fields are copied into a newly allocated font
    122 ** structure, so that the pixmap may be translated directly.
    123 ** If any of the colors is null, it will be assumed to be transparent.
    124 ** In color index mode, the specified colors have to be preallocated.
    125 */
     125
     126/**
     127 * @brief Draws text in a specific font to a pixmap.
     128 *
     129 * The results are written to the pixmap's index buffer. Contents of the
     130 * foreground and background fields are copied into a newly allocated font
     131 * structure, so that the pixmap may be translated directly. If any of the
     132 * colors is null, it will be assumed to be transparent.
     133 * In color index mode, the specified colors have to be preallocated.
     134 *
     135 * @param[in] font                      The font to use for drawing
     136 * @param[in] text                      The start of the text to draw
     137 * @param[in] characters        The number of characters to draw
     138 * @param[in] fg0                       The first foreground color
     139 * @param[in] fg1                       The second foreground color
     140 * @param[in] bg                        The background color
     141 * @return                                      The result pixmap, or NULL on error
     142 */
     143gfx_pixmap_t *gfxr_draw_font(gfx_bitmap_font_t *font, const char *text,
     144                int characters, PaletteEntry *fg0, PaletteEntry *fg1,
     145                PaletteEntry *bg);
     146/** @} */
    126147
    127148} // End of namespace Sci
    128149
  • engines/sci/gfx/gfx_driver.h

    diff --git a/engines/sci/gfx/gfx_driver.h b/engines/sci/gfx/gfx_driver.h
    index b74511d..4768936 100644
    a b enum gfx_buffer_t {  
    3838};
    3939
    4040
    41 /* Principial graphics driver architecture
    42 ** ---------------------------------------
    43 **
    44 ** All graphics drivers must provide
    45 ** - One visual front buffer (the actually visible thing)
    46 ** - Two dynamic back buffers:
    47 **   + visual
    48 **   + priority
    49 ** - Two static buffers  (containing the background image and picviews):
    50 **   + visual
    51 **   + priority
    52 **
    53 ** The control buffer is handled outside the graphics driver architecture.
    54 ** Graphics are drawn by first setting the static buffers, then updating
    55 ** the back buffers (from the static buffers), adding all picviews and other
    56 ** widgets, and finally updating the front buffer.
    57 **
    58 ** All coordinates refer to the scaled coordinate system.
    59 ** Invalid parameters should produce an error message.
    60 ** Support for some valid parameter values is optional (like different line
    61 ** modes). If an unsupported but valid parameter is specified, the function
    62 ** must use a reasonable default value.
    63 */
    64 
     41/**
     42 * @brief Graphics driver.
     43 *
     44 * Principial graphics driver architecture:
     45 *
     46 * All graphics drivers must provide
     47 * - One visual front buffer (the actually visible thing)
     48 * - Two dynamic back buffers:
     49 *   - visual
     50 *   - priority
     51 * - Two static buffers  (containing the background image and picviews):
     52 *   - visual
     53 *   - priority
     54 *
     55 * The control buffer is handled outside the graphics driver architecture.
     56 * Graphics are drawn by first setting the static buffers, then updating
     57 * the back buffers (from the static buffers), adding all picviews and other
     58 * widgets, and finally updating the front buffer.
     59 *
     60 * All coordinates refer to the scaled coordinate system.
     61 * Invalid parameters should produce an error message.
     62 * Support for some valid parameter values is optional (like different line
     63 * modes). If an unsupported but valid parameter is specified, the function
     64 * must use a reasonable default value.
     65 */
    6566class GfxDriver {
    6667public:
    67         /*** Initialization ***/
    68 
     68        /** @name Initialization */
     69        /** @{ */
     70        /**
     71         * @brief Attempts to initialize a specific graphics mode.
     72         *
     73         * The scaling factors apply to the standard SCI resolution of 320x200
     74         * pixels and is used for internal representation of graphical data.
     75         * The physical resolution set by the graphics driver may be different
     76         * for practical reasons.
     77         * Must also set _mode, preferably with the gfx_new_mode() function
     78         * specified in gfx_tools.h.
     79         *
     80         * @param[in] xfact             Horizontal scaling factor
     81         * @param[in] yfact             Vertical scaling factor
     82         * @param[in] bytespp   Any of GFX_COLOR_MODE_*. GFX_COLOR_MODE_INDEX
     83         *                                              implies color index mode.
     84         * @return                              GFX_OK on success, GFX_ERROR if the mode could
     85         *                                              not be set, or GFX_FATAL if the graphics target
     86         *                                              is unuseable.
     87         */
    6988        GfxDriver(int xfact, int yfact, int bytespp);
    70         /* Attempts to initialize a specific graphics mode
    71         ** Parameters: (int x int) xres, yres: Horizontal and vertical scaling
    72         **                         factors
    73         **             (int) bytespp: Any of GFX_COLOR_MODE_*. GFX_COLOR_MODE_INDEX
    74         **                   implies color index mode.
    75         ** Returns   : (int) GFX_OK on success, GFX_ERROR if the mode could not be
    76         **                   set, or GFX_FATAL if the graphics target is unuseable.
    77         ** The scaling factors apply to the standard SCI resolution of 320x200 pixels
    78         ** and is used for internal representation of graphical data. The physical
    79         ** resolution set by the graphics driver may be different for practical
    80         ** reasons.
    81         ** Must also set _mode, preferably with the gfx_new_mode() function
    82         ** specified in gfx_tools.h.
    83         */
    8489
     90        /**
     91         * @brief Uninitializes the current graphics mode.
     92         *
     93         * This function frees all memory allocated by the graphics driver,
     94         * including mode and palette information, uninstalls all console
     95         * commands introduced by preceeding init() or init_specific()
     96         * commands, and does any clean-up work (like closing visuals or
     97         * returning to text mode) required by the graphics infrastructure used.
     98         */
    8599        ~GfxDriver();
    86         /* Uninitializes the current graphics mode
    87         ** This function frees all memory allocated by the graphics driver,
    88         ** including mode and palette information, uninstalls all console commands
    89         ** introduced by preceeding init() or init_specific() commands, and does any
    90         ** clean-up work (like closing visuals or returning to text mode) required by
    91         ** the graphics infrastructure used.
    92         */
    93 
    94 
    95         /*** Drawing operations ***/
    96 
     100        /** @} */
     101
     102        /** @name Drawing operations */
     103        /** @{ */
     104
     105        /**
     106         * @brief Draws a single line to the back buffer.
     107         *
     108         * Note that color.priority is relevant and must be drawn if
     109         * (color.mask & GFX_MASK_PRIORITY). Support for line modes other than
     110         * GFX_LINE_MODE_FAST is optional. For non-fine lines, the coordinates
     111         * provided describe the upper left corner of the pixels of the line
     112         * to draw.line_style support is optional, if
     113         * GFX_CAPABILITY_STIPPLED_LINES is not set.
     114         *
     115         * @param[in] start     Starting point of the line to draw
     116         * @param[in] end                       End point of the line to draw
     117         * @param[in] color                     The color to draw with
     118         * @param[in] line_mode         Any of the line modes
     119         * @param[in] line_style        Any of the line styles
     120         * @return                                      GFX_OK or GFX_FATAL
     121         */
    97122        int drawLine(Common::Point start, Common::Point end, gfx_color_t color,
    98123                     gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    99         /* Draws a single line to the back buffer.
    100         ** Parameters: (Common::Point) start: Starting point of the line to draw
    101         **             (Common::Point) end: End point of the line to draw
    102         **             (gfx_color_t *) color: The color to draw with
    103         **             (int) line_mode: Any of the line modes
    104         **             (int) line_style: Any of the line styles
    105         ** Returns   : (int) GFX_OK or GFX_FATAL
    106         ** Note that color.priority is relevant and must be drawn if
    107         ** (color.mask & GFX_MASK_PRIORITY).
    108         ** Support for line modes other than GFX_LINE_MODE_FAST is optional.
    109         ** For non-fine lines, the coordinates provided describe the upper left
    110         ** corner of the pixels of the line to draw.
    111         ** line_style support is optional, if GFX_CAPABILITY_STIPPLED_LINES is not
    112         ** set.
    113         */
    114124
     125        /**
     126         * @brief Draws a single filled and possibly shaded rectangle to the back
     127         * buffer.
     128         *
     129         * Note that color.priority is relevant and must be drawn if
     130         * (color.mask & GFX_MASK_PRIORITY). color2 is relevant only if
     131         * shade_mode is not GFX_SHADE_FLAT. Support for shade modes other
     132         * than GFX_SHADE_FLAT is optional.
     133         *
     134         * @param[in] rect                      The rectangle to draw
     135         * @param[in] color1            The first color to draw with
     136         * @param[in] color2            The second color to draw with
     137         * @param[in] shade_mode        Any of GFX_SHADE_*.
     138         * @return                                      GFX_OK or GFX_FATAL
     139         */
    115140        int drawFilledRect(rect_t rect, gfx_color_t color1, gfx_color_t color2,
    116141                           gfx_rectangle_fill_t shade_mode);
    117         /* Draws a single filled and possibly shaded rectangle to the back buffer.
    118         ** Parameters: (rect_t *) rect: The rectangle to draw
    119         **             (gfx_color_t *) color1, color2: The colors to draw with
    120         **             (int) shade_mode: Any of GFX_SHADE_*.
    121         ** Returns   : (int) GFX_OK or GFX_FATAL
    122         ** Note that color.priority is relevant and must be drawn if
    123         ** (color.mask & GFX_MASK_PRIORITY).
    124         ** color2 is relevant only if shade_mode is not GFX_SHADE_FLAT.
    125         ** Support for shade modes other than GFX_SHADE_FLAT is optional.
    126         */
    127 
    128         /*** Pixmap operations ***/
    129 
     142        /** @} */
     143
     144        /** @name Pixmap operations */
     145        /** @{ */
     146
     147        /**
     148         * @brief Draws part of a pixmap to the static or back buffer.
     149         *
     150         * @param[in] pxm               The pixmap to draw
     151         * @param[in] priority  The priority to draw with, or GFX_NO_PRIORITY
     152         *                                              to draw on top of everything without setting the
     153         *                                              priority back buffer.
     154         * @param[in] src               The pixmap-relative source rectangle
     155         * @param[in] dest              The destination rectangle
     156         * @param[in] buffer    One of GFX_BUFFER_STATIC and GFX_BUFFER_BACK
     157         * @return                              GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was
     158         *                                              not (but should have been) registered.
     159         */
    130160        int drawPixmap(gfx_pixmap_t *pxm, int priority,
    131161                       rect_t src, rect_t dest, gfx_buffer_t buffer);
    132         /* Draws part of a pixmap to the static or back buffer
    133         ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to draw
    134         **             (int) priority: The priority to draw with, or GFX_NO_PRIORITY
    135         **                   to draw on top of everything without setting the
    136         **                   priority back buffer
    137         **             (rect_t) src: The pixmap-relative source rectangle
    138         **             (rect_t) dest: The destination rectangle
    139         **             (int) buffer: One of GFX_BUFFER_STATIC and GFX_BUFFER_BACK
    140         ** Returns   : (int) GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was not
    141         **                   (but should have been) registered.
    142         */
    143162
     163        /**
     164         * @brief Grabs an image from the visual or priority back buffer.
     165         *
     166         * This function is now mandatory.
     167         *
     168         * @param[in] src       The rectangle to grab
     169         * @param[in] pxm       The pixmap structure the data is to be written to
     170         * @param[in] map       GFX_MASK_VISUAL or GFX_MASK_PRIORITY
     171         * @return                      GFX_OK, GFX_FATAL, or GFX_ERROR for invalid map
     172         *                                      values pxm may be assumed to be empty and
     173         *                                      pre-allocated with an appropriate memory size.
     174         */
    144175        int grabPixmap(rect_t src, gfx_pixmap_t *pxm, gfx_map_mask_t map);
    145         /* Grabs an image from the visual or priority back buffer
    146         ** Parameters: (rect_t) src: The rectangle to grab
    147         **             (gfx_pixmap_t *) pxm: The pixmap structure the data is to
    148         **                              be written to
    149         **             (int) map: GFX_MASK_VISUAL or GFX_MASK_PRIORITY
    150         ** Returns   : (int) GFX_OK, GFX_FATAL, or GFX_ERROR for invalid map values
    151         ** pxm may be assumed to be empty and pre-allocated with an appropriate
    152         ** memory size.
    153         ** This function is now mandatory.
    154         */
    155 
    156 
    157         /*** Buffer operations ***/
    158 
     176        /** @} */
     177
     178        /** @name Buffer operations */
     179        /** @{ */
     180
     181        /**
     182         * @brief Updates the front buffer or the back buffers.
     183         *
     184         * This function updates either the visual front buffer, or the two
     185         * back buffers, by copying the specified source region to the
     186         * destination region.
     187         * For heuristical reasons, it may be assumed that the x and y fields
     188         * of src and dest will be identical in /most/ cases.If they aren't,
     189         * the priority map will not be required to be copied.
     190         *
     191         * @param[in] src:              Source rectangle
     192         * @param[in] dest:             Destination point
     193         * @param[in] buffer:   One of GFX_BUFFER_FRONT or GFX_BUFFER_BACK
     194         * @return                              GFX_OK, GFX_ERROR or GFX_FATAL
     195         */
    159196        int update(rect_t src, Common::Point dest, gfx_buffer_t buffer);
    160         /* Updates the front buffer or the back buffers
    161         ** Parameters: (rect_t) src: Source rectangle
    162         **             (Common::Point) dest: Destination point
    163         **             (int) buffer: One of GFX_BUFFER_FRONT or GFX_BUFFER_BACK
    164         ** Returns   : (int) GFX_OK, GFX_ERROR or GFX_FATAL
    165         ** This function updates either the visual front buffer, or the two back
    166         ** buffers, by copying the specified source region to the destination
    167         ** region.
    168         ** For heuristical reasons, it may be assumed that the x and y fields of
    169         ** src and dest will be identical in /most/ cases.
    170         ** If they aren't, the priority map will not be required to be copied.
    171         */
    172197
     198        /**
     199         * @brief Sets the contents of the static visual and priority buffers.
     200         *
     201         * pic and priority may be modified or written to freely. They may also
     202         * be used as the actual static buffers, since they are not freed and
     203         * reallocated between calls to set_static_buffer() and update(),
     204         * unless exit() was called in between.
     205         * Note that later version of the driver interface may disallow
     206         * modifying pic and priority. pic and priority are always scaled to
     207         * the appropriate resolution
     208         *
     209         * @param[in] pic               The image defining the new content of the
     210         *                                              visual back buffer
     211         * @param[in] priority  The priority map containing the new content of
     212         *                                              the priority back buffer in the index buffer
     213         * @return                              GFX_OK or GFX_FATAL
     214         */
    173215        int setStaticBuffer(gfx_pixmap_t *pic, gfx_pixmap_t *priority);
    174         /* Sets the contents of the static visual and priority buffers
    175         ** Parameters: (gfx_pixmap_t *) pic: The image defining the new content
    176         **                              of the visual back buffer
    177         **             (gfx_pixmap_t *) priority: The priority map containing
    178         **                              the new content of the priority back buffer
    179         **                              in the index buffer
    180         ** Returns   : (int) GFX_OK or GFX_FATAL
    181         ** pic and priority may be modified or written to freely. They may also be
    182         ** used as the actual static buffers, since they are not freed and re-
    183         ** allocated between calls to set_static_buffer() and update(), unless
    184         ** exit() was called in between.
    185         ** Note that later version of the driver interface may disallow modifying
    186         ** pic and priority.
    187         ** pic and priority are always scaled to the appropriate resolution
    188         */
    189 
    190 
    191         /*** Mouse pointer operations ***/
    192 
     216        /** @} */
     217
     218        /** @name Mouse pointer operations */
     219        /** @{ */
     220
     221        /**
     222         * @brief Sets a new mouse pointer.
     223         *
     224         * If pointer is not NULL, it will have been scaled to the appropriate
     225         * size and registered as a pixmap (if neccessary) beforehand. If this
     226         * function is called for a target that supports only two-color
     227         * pointers, the image is a color index image, where only color index
     228         * values 0, 1, and GFX_COLOR_INDEX_TRANSPARENT are used.
     229         *
     230         * @param[in] pointer   The pointer to set, or NULL to set no pointer.
     231         * @param[in] hotspot   The coordinates of the hotspot, or NULL to set
     232         *                                              no pointer.
     233         * @return                              GFX_OK or GFX_FATAL
     234         */
    193235        int setPointer(gfx_pixmap_t *pointer, Common::Point *hotspot);
    194         /* Sets a new mouse pointer.
    195         ** Parameters: (gfx_pixmap_t *) pointer: The pointer to set, or NULL to set
    196         **                              no pointer
    197         **             (Common::Point *) hotspot: The coordinates of the hotspot,
    198         **                               or NULL to set no pointer
    199         ** Returns   : (int) GFX_OK or GFX_FATAL
    200         ** If pointer is not NULL, it will have been scaled to the appropriate
    201         ** size and registered as a pixmap (if neccessary) beforehand.
    202         ** If this function is called for a target that supports only two-color
    203         ** pointers, the image is a color index image, where only color index values
    204         ** 0, 1, and GFX_COLOR_INDEX_TRANSPARENT are used.
    205         */
     236        /** @} */
    206237
    207238        gfx_mode_t *getMode() { return _mode; }
    208239        byte *getVisual0() { return _visual[0]; }
    private:  
    212243
    213244        gfx_pixmap_t *_priority[2];
    214245        byte *_visual[2];
    215         gfx_mode_t *_mode; /* Currently active mode, NULL if no mode is active */
     246        gfx_mode_t *_mode; /**< Currently active mode, NULL if no mode is active */
    216247};
    217248
    218249} // End of namespace Sci
  • engines/sci/gfx/gfx_gui.h

    diff --git a/engines/sci/gfx/gfx_gui.h b/engines/sci/gfx/gfx_gui.h
    index e712d30..cbbaa5c 100644
    a b  
    2323 *
    2424 */
    2525
    26 /* SCI-specific widget handling */
    27 
    2826#ifndef SCI_INCLUDE_SCI_WIDGETS_H
    2927#define SCI_INCLUDE_SCI_WIDGETS_H
    3028
    namespace Sci {  
    3432
    3533class Menu;
    3634
    37 // The following flags are applicable to windows in SCI0
     35/* SCI-specific widget handling */
     36
     37/**
     38 * @brief Flags for windows in SCI0.
     39 */
    3840enum windowFlags {
    39         kWindowTransparent  = 0x01,          // 0000 0001
    40         kWindowNoFrame      = 0x02,          // 0000 0010 - a window without a frame
    41         // Add title bar to window (10 pixels high, framed, text is centered and written in white on dark gray)
    42         kWindowTitle        = 0x04,          // 0000 0100
    43         // bits 3-6 are unused
    44         kWindowDontDraw     = 0x80,          // 1000 0000 - don't draw anything
    45         kWindowNoDropShadow = 0x1000000,     // 0001 0000 0000 0000 0000 0000 0000 (not in SCI)
     41        kWindowTransparent  = 0x01,                     //!< 0000 0001
     42        kWindowNoFrame      = 0x02,                     //!< 0000 0010 - a window without a frame
     43        kWindowTitle        = 0x04,                     /**
     44                                                                                 * 0000 0100 - Add title bar to
     45                                                                                 * window (10 pixels high, framed,
     46                                                                                 * text is centered and written in
     47                                                                                 * white on dark gray), bits 3-6
     48                                                                                 * are unused
     49                                                                                 */
     50        kWindowDontDraw     = 0x80,                     //!< 1000 0000 - don't draw anything
     51        kWindowNoDropShadow = 0x1000000,        //!< 0001 0000 0000 0000 0000 0000 0000 (not in SCI)
    4652        kWindowAutoRestore  = 0x2000000
    4753};
    4854
     55/** @brief Button and frame control flags. */
    4956enum controlStateFlags {
    50         kControlStateEnabled      = 0x0001,  // 0001 - enabled buttons (used by the interpreter)
    51         kControlStateDisabled     = 0x0004,  // 0010 - grayed out buttons (used by the interpreter)
    52         kControlStateFramed       = 0x0008,  // 1000 - widgets surrounded by a frame (used by the interpreter)
    53         kControlStateDitherFramed = 0x1000   // 0001 0000 0000 0000 - widgets surrounded by a dithered frame (used in kgraphics)
     57        kControlStateEnabled      = 0x0001,  //!< 0001 - enabled buttons (used by the interpreter)
     58        kControlStateDisabled     = 0x0004,  //!< 0010 - grayed out buttons (used by the interpreter)
     59        kControlStateFramed       = 0x0008,  //!< 1000 - widgets surrounded by a frame (used by the interpreter)
     60        kControlStateDitherFramed = 0x1000   //!< 0001 0000 0000 0000 - widgets surrounded by a dithered frame (used in kgraphics)
    5461};
    5562
    56 void sciw_set_status_bar(EngineState *s, GfxPort *status_bar, const Common::String &text, int fgcolor, int bgcolor);
    57 /* Sets the contents of a port used as status bar
    58 ** Parmeters: (EngineState *) s: The affected game state
    59 **            (GfxPort *) status_bar: The status bar port
    60 **            (const char *) text: The text to draw
    61 ** Returns  : (void)
    62 */
    63 
    64 GfxPort *sciw_new_window(EngineState *s, rect_t area, int font, gfx_color_t color, gfx_color_t bgcolor,
    65         int title_font, gfx_color_t title_color, gfx_color_t title_bg_color,
    66         const char *title, int flags);
    67 /* Creates a new SCI style window
    68 ** Parameters: (EngineState *) s: The affected game state
    69 **             (rect_t) area: The screen area to frame (not including a potential window title)
    70 **             (int) font: Default font number to use
    71 **             (gfx_color_t) color: The foreground color to use for drawing
    72 **             (gfx_color_t) bgcolor: The background color to use
    73 **             (int) title_font: The font to use for the title bar (if any)
    74 **             (gfx_color_t) title_color: Color to use for the title bar text
    75 **             (gfx_color_t) title_bg_color: Color to use for the title bar background
    76 **             (const char *) title: The text to write into the title bar
    77 **             (int) flags: Any ORred combination of window flags
    78 ** Returns   : (GfxPort *) A newly allocated port with the requested characteristics
    79 */
    80 
    81 /*---------------------*/
    82 /*** Control widgets ***/
    83 /*---------------------*/
    84 
    85 GfxList *sciw_new_button_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font, char selected, char inverse, char gray);
    86 /* Creates a new button control list
    87 ** Parameters: (GfxPort *) port: The port containing the color values to use for the
    88 **                                   button (the button is /not/ appended to the port there)
    89 **             (reg_t) ID: Button's ID
    90 **             (rect_t) zone: The area occupied by the button
    91 **             (char *) text: The text to write into the button
    92 **             (int) font: The font to use for the button
    93 **             (char) selected: Whether the button should be marked as being selected by the keyboard focus
    94 **             (char) inverse: Whether to inverse the color scheme
    95 **             (char) gray: Whether the button should be grayed out
    96 ** Returns   : (GfxList *) The button
    97 */
    98 
    99 GfxList *sciw_new_text_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font,
    100         gfx_alignment_t align, char frame, char inverse);
    101 /* Creates a new text control list
    102 ** Parameters: (GfxPort *) port: The port containing the color values to use
    103 **             (reg_t) ID: Text widget ID
    104 **             (rect_t) zone: Area occupied by the text
    105 **             (char *) text: The text
    106 **             (int) font: The font the text is to be drawn in
    107 **             (gfx_alignment_t) align: Horizontal text alignment to use
    108 **             (char) frame: Whether a dithered frame should surround the text
    109 **             (char) inverse: Whether the text colors should be inversed
    110 ** Returns   : (GfxList *) The text control widget list
    111 */
    112 
    113 GfxList *sciw_new_edit_control(GfxPort *port, reg_t ID, rect_t zone, char *text, int font, unsigned int cursor,
    114         char inverse);
    115 /* Creates a new edit control list
    116 ** Parameters: (GfxPort *) port: The port containing the color values to use
    117 **             (reg_t) ID: Text widget ID
    118 **             (rect_t) zone: Area occupied by the text
    119 **             (char *) text: The text
    120 **             (int) font: The font the text is to be drawn in
    121 **             (int) cursor: Cursor position
    122 **             (char) inverse: Whether the edit widget should be reversed
    123 ** Returns   : (GfxList *) An appropriate widget list
    124 */
    125 
    126 GfxList *sciw_new_icon_control(GfxPort *port, reg_t ID, rect_t zone, int view, int loop, int cel,
    127         char frame, char inverse);
    128 /* Creates a new icon control list
    129 ** Parameters: (GfxPort *) port: The port containing the color values to use
    130 **             (reg_t) ID: Text widget ID
    131 **             (rect_t) zone: Area occupied by the text
    132 **             (int x int x int) view, loop, cel: The cel to display
    133 **             (char) frame: Whether the widget should be surrounded by a frame
    134 **             (char) lina inverse: Whether colors should be inversed
    135 ** Returns   : (GfxList *) An appropriate widget list
    136 */
    137 
    138 GfxList *sciw_new_list_control(GfxPort *port, reg_t ID, rect_t zone, int font_nr, char **entries_list,
    139         int entries_nr, int list_top, int selection, char inverse);
    140 /* Creates a new list control list
    141 ** Parameters: (GfxPort *) port: The port containing the color values to use
    142 **             (int) ID: Text widget ID
    143 **             (rect_t) zone: Area occupied by the text
    144 **             (int) font_nr: number of the font to use
    145 **             (char **) entries_list: List of strings to contain within the list
    146 **             (int) entries_nr: Number of entries in entries_list
    147 **             (int) list_top: First list item that is visible
    148 **             (int) selection: The list item that is selected
    149 **             (char) invserse: The usual meaning
    150 ** Returns   : (GfxList *) An appropriate widget list
    151 */
    152 
    153 /*---------------------*/
    154 /*** Menubar widgets ***/
    155 /*---------------------*/
    156 
    157 void sciw_set_menubar(EngineState *s, GfxPort *status_bar, Menubar *menubar, int selection);
    158 /* Draws the menu bar
    159 ** Parameters: (EngineState *) s: The state to operate on
    160 **             (GfxPort *) status_bar: The status bar port to modify
    161 **             (Menubar *) menubar: The menu bar to use
    162 **             (int) selection: Number of the menu to hightlight, or -1 for 'none'
    163 ** Returns   : (void)
    164 */
    165 
    166 GfxPort *sciw_new_menu(EngineState *s, GfxPort *status_bar, Menubar *menubar, int selection);
    167 /* Creates a menu port
    168 ** Parameters: (EngineState *) s: The state to operate on
    169 **             (GfxPort *) status_bar: The status bar
    170 **             (Menubar *) menubar: The menu bar to use
    171 **             (int) selection: Number of the menu to interpret
    172 ** Returns   : (GfxPort *) The result port
    173 */
    174 
    175 GfxPort *sciw_toggle_item(GfxPort *menu_port, Menu *menu, int selection, bool selected);
    176 /* Toggle the selection of a menu item from a menu port
    177 ** Parameters: (GfxPort *) menu_port: The port to modify
    178 **             (Menu *) menu: The menu the menu port corresponds to
    179 **             (int) selection: Number of the menu entry to unselect, or -1 to do a NOP
    180 **             (bool) selected: Whether to set the item's state to selected or not
    181 ** Returns   : (GfxPort *) The modified menu
    182 */
     63/**
     64 * @brief Sets the contents of a port used as status bar.
     65 *
     66 * @param[in] s                         The affected EngineState
     67 * @param[in] status_bar        The status bar port
     68 * @param[in] text                      The text to draw
     69 * @param[in] fgcolor           The foreground color
     70 * @param[in] bgcolor           The background color
     71 */
     72void sciw_set_status_bar(EngineState *s, GfxPort *status_bar,
     73                const Common::String &text, int fgcolor, int bgcolor);
     74
     75/**
     76 * @brief Creates a new SCI style window.
     77 *
     78 * @param[in] s                                 The affected EngineState
     79 * @param[in] area                              The screen area to frame (not including a
     80 *                                                              potential window title)
     81 * @param[in] font                              Default font number to use
     82 * @param[in] color                             The foreground color to use for drawing
     83 * @param[in] bgcolor                   The background color to use
     84 * @param[in] title_font                The font to use for the title bar (if any)
     85 * @param[in] title_color               Color to use for the title bar text
     86 * @param[in] title_bg_color    Color to use for the title bar background
     87 * @param[in] title                             The text to write into the title bar
     88 * @param[in] flags                             Any ORred combination of window flags
     89 * @return      A newly allocated port with the requested characteristics
     90 */
     91GfxPort *sciw_new_window(EngineState *s, rect_t area, int font,
     92                gfx_color_t color, gfx_color_t bgcolor, int title_font,
     93                gfx_color_t title_color, gfx_color_t title_bg_color,
     94                const char *title, int flags);
     95
     96
     97/** @name Control widgets */
     98/** @{ */
     99/**
     100 * @brief Creates a new button control list.
     101 *
     102 * @param[in] port              The port containing the color values to use for the
     103 *                                              button (the button is /not/ appended to the port
     104 *                                              there)
     105 * @param[in] ID                Button's ID
     106 * @param[in] zone              The area occupied by the button
     107 * @param[in] text              The text to write into the button
     108 * @param[in] font              The font to use for the button
     109 * @param[in] selected  Whether the button should be marked as being
     110 *                                              selected by the keyboard focus
     111 * @param[in] inverse   Whether to inverse the color scheme
     112 * @param[in] gray              Whether the button should be grayed out
     113 * @return                              The button
     114 */
     115GfxList *sciw_new_button_control(GfxPort *port, reg_t ID, rect_t zone,
     116                char *text, int font, char selected, char inverse, char gray);
     117
     118/**
     119 * @brief Creates a new text control list.
     120 *
     121 * @param[in] port              The port containing the color values to use
     122 * @param[in] ID                Text widget ID
     123 * @param[in] zone              Area occupied by the text
     124 * @param[in] text              The text
     125 * @param[in] font              The font the text is to be drawn in
     126 * @param[in] align             Horizontal text alignment to use
     127 * @param[in] frame             Whether a dithered frame should surround the text
     128 * @param[in] inverse   Whether the text colors should be inversed
     129 * @return                              The text control widget list
     130 */
     131GfxList *sciw_new_text_control(GfxPort *port, reg_t ID, rect_t zone,
     132                char *text, int font, gfx_alignment_t align, char frame,
     133                char inverse);
     134
     135/**
     136 * @brief Creates a new edit control list.
     137 *
     138 * @param[in] port              The port containing the color values to use
     139 * @param[in] ID                Text widget ID
     140 * @param[in] zone              Area occupied by the text
     141 * @param[in] text              The text
     142 * @param[in] font              The font the text is to be drawn in
     143 * @param[in] cursor    Cursor position
     144 * @param[in] inverse   Whether the edit widget should be reversed
     145 * @return                              An appropriate widget list
     146 */
     147GfxList *sciw_new_edit_control(GfxPort *port, reg_t ID, rect_t zone,
     148                char *text, int font, unsigned int cursor, char inverse);
     149
     150/**
     151 * @brief Creates a new icon control list.
     152 *
     153 * @param[in] port              The port containing the color values to use
     154 * @param[in] ID                Text widget ID
     155 * @param[in] zone              Area occupied by the text
     156 * @param[in] view              The view index
     157 * @param[in] loop              The loop index
     158 * @param[in] cel               The cel to display
     159 * @param[in] frame             Whether the widget should be surrounded by a frame
     160 * @param[in] inverse   Whether colors should be inversed
     161 * @return                              An appropriate widget list
     162 */
     163GfxList *sciw_new_icon_control(GfxPort *port, reg_t ID, rect_t zone,
     164                int view, int loop, int cel, char frame, char inverse);
     165
     166/**
     167 * @brief Creates a new list control list.
     168 *
     169 * @param[in] port:                     The port containing the color values to use
     170 * @param[in] ID:                       Text widget ID
     171 * @param[in] zone:                     Area occupied by the text
     172 * @param[in] font_nr:          Number of the font to use
     173 * @param[in] entries_list:     List of strings to contain within the list
     174 * @param[in] entries_nr:       Number of entries in entries_list
     175 * @param[in] list_top:         First list item that is visible
     176 * @param[in] selection:        The list item that is selected
     177 * @param[in] inverse:          The usual meaning
     178 * @return                                      An appropriate widget list
     179 */
     180GfxList *sciw_new_list_control(GfxPort *port, reg_t ID, rect_t zone,
     181                int font_nr, char **entries_list, int entries_nr, int list_top,
     182                int selection, char inverse);
     183/** @} */
     184
     185/** @name Menubar widgets */
     186/** @{ */
     187
     188/**
     189 * @brief Draws the menu bar.
     190 *
     191 * @param[in] s:                        The EngineState to operate on
     192 * @param[in] status_bar:       The status bar port to modify
     193 * @param[in] menubar:          The menu bar to use
     194 * @param[in] selection:        Number of the menu to hightlight, or -1 for
     195 *                                                      'none'
     196 */
     197void sciw_set_menubar(EngineState *s, GfxPort *status_bar, Menubar *menubar,
     198                int selection);
     199
     200/**
     201 * @brief Creates a menu port.
     202 *
     203 * @param[in] s                         The state to operate on
     204 * @param[in] status_bar        The status bar
     205 * @param[in] menubar           The menu bar to use
     206 * @param[in] selection         Number of the menu to interpret
     207 * @return                                      The result port
     208 */
     209GfxPort *sciw_new_menu(EngineState *s, GfxPort *status_bar,
     210                Menubar *menubar, int selection);
     211
     212/**
     213 * @brief Toggle the selection of a menu item from a menu port.
     214 *
     215 * @param[in] menu_port The port to modify
     216 * @param[in] menu              The menu the menu port corresponds to
     217 * @param[in] selection Number of the menu entry to unselect, or -1 to do
     218 *                                              a NOP
     219 * @param[in] selected  Whether to set the item's state to selected or not
     220 * @return                              The modified menu
     221 */
     222GfxPort *sciw_toggle_item(GfxPort *menu_port, Menu *menu, int selection,
     223                bool selected);
     224/** @} */
    183225
    184226} // End of namespace Sci
    185227
  • engines/sci/gfx/gfx_options.h

    diff --git a/engines/sci/gfx/gfx_options.h b/engines/sci/gfx/gfx_options.h
    index 393627a..f929bb7 100644
    a b  
    4242
    4343namespace Sci {
    4444
    45 /* Dirty rectangle heuristics: */
    46 
    47 /* One: Redraw one rectangle surrounding the dirty area (insert is O(1)) */
    48 #define GFXOP_DIRTY_FRAMES_ONE 1
    49 
    50 /* Clusters: Accumulate dirty rects, merging those that overlap (insert is O(n))  */
    51 #define GFXOP_DIRTY_FRAMES_CLUSTERS 2
     45/** @brief Dirty rectangle heuristics. */
     46enum {
     47        GFXOP_DIRTY_FRAMES_ONE = 1, /**< One: Redraw one rectangle surrounding the dirty area (insert is O(1)) */
     48        GFXOP_DIRTY_FRAMES_CLUSTERS = 2 /**< Clusters: Accumulate dirty rects, merging those that overlap (insert is O(n))  */
     49};
    5250
     51/**
     52 * @brief All user options to the rendering pipeline
     53 *
     54 * See note in sci_conf.h for config_entry_t before changing types of
     55 * variables
     56 */
    5357struct gfx_options_t {
    5458#ifdef CUSTOM_GRAPHICS_OPTIONS
    55         /* gfx_options_t: Contains all user options to the rendering pipeline */
    56         /* See note in sci_conf.h for config_entry_t before changing types of
    57         ** variables */
    58 
    5959        int buffer_pics_nr; /* Number of unused pics to buffer */
    6060
    6161        /* SCI0 pic resource options */
  • engines/sci/gfx/gfx_res_options.h

    diff --git a/engines/sci/gfx/gfx_res_options.h b/engines/sci/gfx/gfx_res_options.h
    index f01f93d..7ae159c 100644
    a b  
    2323 *
    2424 */
    2525
    26 /* Configuration options for per-resource customisations */
    27 
    2826#ifndef SCI_GFX_GFX_RES_OPTIONS_H
    2927#define SCI_GFX_GFX_RES_OPTIONS_H
    3028
     
    3533#include "sci/gfx/gfx_resmgr.h"
    3634
    3735namespace Sci {
     36/** @name Configuration options for per-resource customisations */
     37/** @{ */
    3838
    3939struct gfx_res_pattern_t {
    4040        int min, max;
    4141};
    4242
    43 /* GFX resource assignments */
    44 
     43/**
     44 * @brief GFX resource assignments.
     45 */
    4546struct gfx_res_assign_t {
    4647        union {
    4748                struct {
    struct gfx_res_assign_t {  
    5253};
    5354
    5455
    55 /* GFX resource modifications */
    56 
     56/**
     57 * @brief GFX resource modifications/
     58 */
    5759struct gfx_res_conf_t {
    58         int type; /* Resource type-- only one allowed */
     60        int type; /**< Resource type-- only one allowed */
    5961
    6062        /* If any of the following is 0, it means that there is no restriction.
    6163        ** Otherwise, one of the patterns associated with them must match. */
    62         int patterns_nr; /* Number of patterns (only 'view' patterns for views) */
    63         int loops_nr, cels_nr; /* Number of loop/cel patterns, for views only.
     64        int patterns_nr; /**< Number of patterns (only 'view' patterns for views) */
     65        int loops_nr, cels_nr; /**< Number of loop/cel patterns, for views only.
    6466                               ** For pics, loops_nr identifies the palette. */
    6567
    6668        gfx_res_pattern_t *patterns;
    6769
    6870        union {
    6971                gfx_res_assign_t assign;
    70                 byte factor[3]; /* divide by 16 to retrieve factor */
    71         } conf; /* The actual configuration */
     72                byte factor[3]; /**< divide by 16 to retrieve factor */
     73        } conf; /**< The actual configuration */
    7274
    7375        gfx_res_conf_t *next;
    7476};
    struct gfx_res_fullconf_t {  
    8486
    8587struct gfx_options_t;
    8688
     89/**
     90 * @brief Configures a graphical pixmap according to config options.
     91 *
     92 * Modifies pxm as considered appropriate by configuration options. Does
     93 * not do anything in colour index mode.
     94 *
     95 * @param[in] options   The options according to which configuration
     96 *                                              should be performed
     97 * @param[in] pxm               The pixmap to configure
     98 * @return                              0 on success, non-zero otherwise
     99 */
    87100int gfx_get_res_config(gfx_options_t *options, gfx_pixmap_t *pxm);
    88 /* Configures a graphical pixmap according to config options
    89 ** Parameters: (gfx_options_t *) options: The options according to which
    90 **                                        configuration should be performed
    91 **             (gfx_resource_type_t) pxm: The pixmap to configure
    92 ** Returns   : (int) 0 on success, non-zero otherwise
    93 ** Modifies pxm as considered appropriate by configuration options. Does
    94 ** not do anything in colour index mode.
    95 */
    96101
     102/** @} */
    97103} // End of namespace Sci
    98104
    99105#endif
  • engines/sci/gfx/gfx_resmgr.h

    diff --git a/engines/sci/gfx/gfx_resmgr.h b/engines/sci/gfx/gfx_resmgr.h
    index c5878bf..bdd3407 100644
    a b enum gfx_resource_type_t {  
    4949        GFX_RESOURCE_TYPE_PALETTE,
    5050        /* FIXME: Add PAL resource */
    5151
    52         GFX_RESOURCE_TYPES_NR /* Number of resource types that are to be supported */
     52        GFX_RESOURCE_TYPES_NR /**< Number of resource types that are to be supported */
    5353};
    5454
    5555#define GFX_RESOURCE_TYPE_0 GFX_RESOURCE_TYPE_VIEW
    enum gfx_resource_type_t {  
    5858#define GFXR_RES_TYPE(id) (id >> 16)
    5959#define GFXR_RES_NR(id) (id & 0xffff)
    6060
    61 
     61/** @brief Graphics resource */
    6262struct gfx_resource_t {
    63         int ID; /* Resource ID */
    64         int lock_sequence_nr; /* See description of lock_counter in GfxResManager */
    65         int mode; /* A mode type hash */
     63        int ID;                                 /**< Resource ID */
     64        int lock_sequence_nr;   /**< See description of lock_counter in GfxResManager */
     65        int mode;                               /**< A mode type hash */
    6666
     67        /** Scaled pic */
    6768        union {
    6869                gfx_pixmap_t *pointer;
    6970                gfxr_view_t *view;
    struct gfx_resource_t {  
    7172                gfxr_pic_t *pic;
    7273        } scaled_data;
    7374
     75        /** Original pic */
    7476        union {
    7577                gfx_pixmap_t *pointer;
    7678                gfxr_view_t *view;
    struct gfx_options_t;  
    8587
    8688typedef Common::HashMap<int, gfx_resource_t *> IntResMap;
    8789
    88 
     90/** @brief Graphics resource manager */
    8991class GfxResManager {
    9092public:
    91         GfxResManager(int version, bool isVGA, gfx_options_t *options, GfxDriver *driver, ResourceManager *resManager);
     93        GfxResManager(int version, bool isVGA, gfx_options_t *options,
     94                        GfxDriver *driver, ResourceManager *resManager);
    9295
    9396        ~GfxResManager();
    9497
    95         /* Calculates a unique hash value for the specified options/type setup
    96         ** Parameters: (gfx_resource_type_t) type: The type the hash is to be generated for
    97         ** Returns   : (int) A hash over the values of the options entries, covering entries iff
    98         **                   they are relevant for the specified type
    99         ** Covering more entries than relevant may slow down the system when options are changed,
    100         ** while covering less may result in invalid cached data being used.
    101         ** Only positive values may be returned, as negative values are used internally by the generic
    102         ** resource manager code.
    103         ** Also, only the lower 20 bits are available to the interpreter.
    104         ** (Yes, this isn't really a "hash" in the traditional sense...)
    105         */
     98        /**
     99         * @brief Calculates a unique hash value for the specified options/type
     100         * setup.
     101         *
     102         * Covering more entries than relevant may slow down the system when
     103         * options are changed, while covering less may result in invalid
     104         * cached data being used.
     105         * Only positive values may be returned, as negative values are used
     106         * internally by the generic resource manager code.
     107         * Also, only the lower 20 bits are available to the interpreter.
     108         * (Yes, this isn't really a "hash" in the traditional sense...)
     109         *
     110         * @param[in] type      The type the hash is to be generated for
     111         * @return                      A hash over the values of the options entries,
     112         *                                      covering entries iff they are relevant for the
     113         *                                      specified type.
     114         */
    106115        int getOptionsHash(gfx_resource_type_t type);
    107116
    108117
    109         /* 'Tags' all resources for deletion
    110         ** Paramters: (void)
    111         ** Returns  : (void)
    112         ** Tagged resources are untagged if they are referenced.
    113         */
     118        /**
     119         * @brief 'Tags' all resources for deletion.
     120         *
     121         * Tagged resources are untagged if they are referenced.
     122         */
    114123        void tagResources() { _tagLockCounter++; }
    115124
    116125
    117         /* Retrieves an SCI0/SCI01 mouse cursor
    118         ** Parameters: (int) num: The cursor number
    119         ** Returns   : (gfx_font_t *) The approprate cursor as a pixmap, or NULL on error
    120         */
     126        /**
     127         * @brief Retrieves an SCI0/SCI01 mouse cursor.
     128         *
     129         * @param[in] num       The cursor number
     130         * @return                      The approprate cursor as a pixmap, or NULL on error
     131         */
    121132        gfx_pixmap_t *getCursor(int num);
    122133
    123134
    124         /* Retrieves the static palette from the interpreter-specific code
    125         ** Parameters: (int *) colors_nr: Number of colors to use
    126         **             (int) nr: The palette to read
    127         ** Returns   : (Palette *) static palette
    128         **             if a static palette must be used, NULL otherwise
    129         */
     135        /**
     136         * @brief Retrieves the static palette from the interpreter-specific code.
     137         *
     138         * @param[in] colors_nr Number of colors to use
     139         * @param[in] num               The palette to read
     140         * @return                              Static palette if a static palette must be
     141         *                                              used, NULL otherwise
     142         */
    130143        Palette *getPalette(int *colors_nr, int num = 999);
    131144
    132145
    133         /* Retrieves a font
    134         ** Parameters: (int) nr: The font number
    135         **             (int) scaled: Whether the font should be font-scaled
    136         ** Returns   : (gfx_font_t *) The appropriate font, or NULL on error
    137         */
     146        /**
     147         * @brief Retrieves a font.
     148         *
     149         * @param[in] num               The font number
     150         * @param[in] scaled    Whether the font should be font-scaled
     151         * @return                              The appropriate font, or NULL on error
     152         */
    138153        gfx_bitmap_font_t *getFont(int num, bool scaled = false);
    139154
    140155
    141         /* Retrieves a translated view cel
    142         ** Parameters:
    143         **             (int) nr: The view number
    144         **             (int *) loop: Pointer to a variable containing the loop number
    145         **             (int *) cel: Pointer to a variable containing the cel number
    146         **                 (int) palette: The palette to use
    147         ** Returns   : (gfx_view_t *) The relevant view, or NULL if nr was invalid
    148         ** loop and cel are given as pointers in order to allow the underlying variables to be
    149         ** modified if they are invalid (this is relevant for SCI version 0, where invalid
    150         ** loop and cel numbers have to be interpreted as 'maximum' or 'minimum' by the interpreter)
    151         */
     156        /**
     157         * @brief Retrieves a translated view cel.
     158         *
     159         * @param[in] nr                The view number
     160         * @param[in] loop              Pointer to a variable containing the loop number
     161         * @param[in] cel               Pointer to a variable containing the cel number
     162         * @param[in] palette   The palette to use
     163         * @return                              The relevant view, or NULL if nr was invalid
     164         *                                              loop and cel are given as pointers in order to
     165         *                                              allow the underlying variables to be modified
     166         *                                              if they are invalid (this is relevant for SCI
     167         *                                              version 0, where invalid loop and cel numbers
     168         *                                              have to be interpreted as 'maximum' or 'minimum'
     169         *                                              by the interpreter)
     170         */
    152171        gfxr_view_t *getView(int nr, int *loop, int *cel, int palette);
    153172
    154173
    155         /* Retrieves a displayable (translated) pic resource
    156         ** Parameters: (int) nr: Number of the pic resource
    157         **             (int) maps: The maps to translate (ORred GFX_MASK_*)
    158         **             (int) flags: Interpreter-dependant pic flags
    159         **             (int) default_palette: The default palette to use for drawing (if applicable)
    160         **             (bool) scaled: Whether to return the scaled maps, or the unscaled
    161         **                           ones (which may be identical) for some special operations.
    162         ** Returns   : (gfxr_pic_t *) The appropriate pic resource with all maps as index (but not
    163         **                           neccessarily translated) data.
    164         */
    165         gfxr_pic_t *getPic(int num, int maps, int flags, int default_palette, bool scaled = false);
    166 
    167 
    168         /* Retrieves a displayable (translated) pic resource written ontop of an existing pic
    169         ** Parameters: (int) old_nr: Number of the pic resource to write on
    170         **             (int) new_nr: Number of the pic resource that is to be added
    171         **             (int) flags: Interpreter-dependant pic flags
    172         **             (int) default_palette: The default palette to use for drawing (if applicable)
    173         **             (int) scaled: Whether to return the scaled maps, or the unscaled
    174         **                           ones (which may be identical) for some special operations.
    175         ** Returns   : (gfxr_pic_t *) The appropriate pic resource with all maps as index (but not
    176         **                           neccessarily translated) data.
    177         ** This function invalidates the cached pic pointed to by old_nr in the cache. While subsequent
    178         ** addToPic() writes will still modify the 'invalidated' pic, gfxr_get_pic() operations will
    179         ** cause it to be removed from the cache and to be replaced by a clean version.
    180         */
    181         gfxr_pic_t *addToPic(int old_nr, int new_nr, int flags, int old_default_palette, int default_palette);
    182 
    183         /* Calculate a picture
    184         ** Parameters: (gfxr_pic_t *) scaled_pic: The pic structure that is to be written to
    185         **             (gfxr_pic_t *) unscaled_pic: The pic structure the unscaled pic is to be written to,
    186         **                                          or NULL if it isn't needed.
    187         **             (int) flags: Pic drawing flags (interpreter dependant)
    188         **             (int) default_palette: The default palette to use for pic drawing (interpreter dependant)
    189         **             (int) nr: pic resource number
    190         ** Returns   : (int) GFX_ERROR if the resource could not be found, GFX_OK otherwise
    191         */
    192         int calculatePic(gfxr_pic_t *scaled_pic, gfxr_pic_t *unscaled_pic, int flags, int default_palette, int nr);
    193 
    194         /* Determines whether support for pointers with more than two colors is required
    195         ** Returns   : (bool) false if no support for multi-colored pointers is required, true
    196         **                   otherwise
    197         */
     174        /**
     175         * @brief Retrieves a displayable (translated) pic resource.
     176         *
     177         * @param[in] num                               Number of the pic resource
     178         * @param[in] maps                              The maps to translate (ORred GFX_MASK_*)
     179         * @param[in] flags                             Interpreter-dependant pic flags
     180         * @param[in] default_palette   The default palette to use for drawing
     181         *                                                              (if applicable)
     182         * @param[in] scaled                    Whether to return the scaled maps, or
     183         *                                                              the unscaled ones (which may be
     184         *                                                              identical) for some special operations.
     185         * @return                                              The appropriate pic resource with all
     186         *                                                              maps as index (but not neccessarily
     187         *                                                              translated) data.
     188         */
     189        gfxr_pic_t *getPic(int num, int maps, int flags, int default_palette,
     190                        bool scaled = false);
     191
     192
     193        /**
     194         * @brief Retrieves a displayable (translated) pic resource written ontop of
     195         * an existing pic.
     196         *
     197         * This function invalidates the cached pic pointed to by old_nr in the
     198         * cache. While subsequent addToPic() writes will still modify the
     199         * 'invalidated' pic, gfxr_get_pic() operations will cause it to be
     200         * removed from the cache and to be replaced by a clean version.
     201         *
     202         * @param[in] old_nr                            Number of the pic resource to write on
     203         * @param[in] new_nr                            Number of the pic resource that is to
     204         *                                                                      be added
     205         * @param[in] flags                                     Interpreter-dependant pic flags
     206         * @param[in] old_default_palette       The default palette of the pic before
     207         *                                                                      translation
     208         * @param[in] default_palette           The default palette to use for drawing
     209         *                                                                      (if applicable)
     210         * @return                                                      The appropriate pic resource with all
     211         *                                                                      maps as index (but not neccessarily
     212         *                                                                      translated) data.
     213         */
     214        gfxr_pic_t *addToPic(int old_nr, int new_nr, int flags,
     215                        int old_default_palette, int default_palette);
     216
     217        /**
     218         * @brief Calculate a picture
     219         *
     220         * @param[in] scaled_pic                The pic structure that is to be
     221         *                                                              written to
     222         * @param[in] unscaled_pic              The pic structure the unscaled pic is
     223         *                                                              to be written to, or NULL if it isn't
     224         *                                                              needed.
     225         * @param[in] flags                             Pic drawing flags (interpreter
     226         *                                                              dependant)
     227         * @param[in] default_palette   The default palette to use for pic
     228         *                                                              drawing (interpreter dependant)
     229         * @param[in] nr                                pic resource number
     230         * @return                                              GFX_ERROR if the resource could not be
     231         *                                                              found, GFX_OK otherwise
     232         */
     233        int calculatePic(gfxr_pic_t *scaled_pic, gfxr_pic_t *unscaled_pic,
     234                        int flags, int default_palette, int nr);
     235
     236        /**
     237         * @brief Determines whether support for pointers with more than two colors
     238         * is required.
     239         *
     240         * @return      false if no support for multi-colored pointers is required,
     241         *                      true otherwise
     242         */
    198243        bool multicoloredPointers() { return _version > SCI_VERSION_1; }
    199244
    200245
    201         /* Frees all resources currently allocated
    202         ** Parameter: (void)
    203         ** Returns  : (void)
    204         ** This function is intended to be used primarily for debugging.
    205         */
     246        /**
     247         * @brief Frees all resources currently allocated.
     248         *
     249         * This function is intended to be used primarily for debugging.
     250         */
    206251        void freeAllResources();
    207252
    208253
    209         /* Frees all tagged resources.
    210         ** Parameters: (void)
    211         ** Returns   : (void)
    212         ** Resources are tagged by calling gfx_tag_resources(), and untagged by calling the
    213         ** approprate dereferenciation function.
    214         ** Note that this function currently only affects view resources, as pic resources are
    215         ** treated differently, while font and cursor resources are relatively rare.
    216         */
     254        /**
     255         * @brief Frees all tagged resources.
     256         *
     257         * Resources are tagged by calling gfx_tag_resources(), and untagged by
     258         * calling the approprate dereferenciation function.
     259         * Note that this function currently only affects view resources, as
     260         * pic resources are treated differently, while font and cursor
     261         * resources are relatively rare.
     262         */
    217263        void freeTaggedResources();
    218264
    219265
    220         /* Frees a previously allocated resource manager, and all allocated resources.
    221         ** Parameters: (void)
    222         ** Return    : (void)
    223         */
     266        /**
     267         * @brief Frees a previously allocated resource manager, and all allocated
     268         * resources.
     269         */
    224270        void freeResManager();
    225271
    226         const PaletteEntry &getColor(int color) { return _staticPalette->getColor(color); }
     272        /**
     273         * @brief Retrieves a color from the static palette
     274         */
     275        const PaletteEntry &getColor(int color)
     276        {
     277                return _staticPalette->getColor(color);
     278        }
    227279
    228         // Set static palette and merge it into the global palette
     280        /**
     281         * @brief Set static palette and merge it into the global palette
     282         */
    229283        void setStaticPalette(Palette *newPalette);
    230284
    231         /*
    232         ** Sets the picture port bounds
    233         */
     285        /**
     286         * @brief Sets the picture port bounds
     287         */
    234288        void changePortBounds(int x1, int y1, int x2, int y2) {
    235289                _portBounds = Common::Rect(x1, y1, x2, y2);
    236290        }
    public:  
    252306        }
    253307#endif
    254308
    255         int getColorCount() { return _staticPalette ? _staticPalette->size() : 0; }
     309        /**
     310         * @brief Gets the number of colors in the static palette.
     311         *
     312         * @return      Number of pallete entries
     313         */
     314        int getColorCount()
     315        {
     316                return _staticPalette ? _staticPalette->size() : 0;
     317        }
    256318
    257319private:
    258320        int _version;
    private:  
    260322        gfx_options_t *_options;
    261323        GfxDriver *_driver;
    262324        Palette *_staticPalette;
    263         int _lockCounter; /* Global lock counter; increased for each new resource allocated.
    264                           ** The newly allocated resource will then be assigned the new value
    265                           ** of the lock_counter, as will any resources referenced afterwards.
    266                           */
    267         int _tagLockCounter; /* lock counter value at tag time */
     325        int _lockCounter;       /**< Global lock counter; increased for each new
     326                                                 * resource allocated. The newly allocated resource will
     327                                                 * then be assigned the new value of the lock_counter,
     328                                                 * as will any resources referenced afterwards. */
     329        int _tagLockCounter; /**< lock counter value at tag time */
    268330        Common::Rect _portBounds;
    269331
    270332        IntResMap _resourceMaps[GFX_RESOURCE_TYPES_NR];
  • engines/sci/gfx/gfx_resource.h

    diff --git a/engines/sci/gfx/gfx_resource.h b/engines/sci/gfx/gfx_resource.h
    index 8ce4a8e..c52f9b9 100644
    a b  
    2323 *
    2424 */
    2525
    26 /* SCI Resource library */
     26/** @file gfx_resource.h
     27 * @brief SCI Resource library.
     28 */
    2729
    2830#ifndef SCI_GFX_GFX_RESOURCE_H
    2931#define SCI_GFX_GFX_RESOURCE_H
    namespace Sci {  
    4446#define GFXR_DITHER_MODE_D16 0  /* Sierra SCI style */
    4547#define GFXR_DITHER_MODE_F256 1 /* Flat color interpolation */
    4648#define GFXR_DITHER_MODE_D256 2 /* 256 color dithering */
     49
    4750/* Dithering patterns */
    4851#define GFXR_DITHER_PATTERN_SCALED 0 /* Dither per pixel on the 320x200 grid */
    4952#define GFXR_DITHER_PATTERN_1 1      /* Dither per pixel on the target */
    namespace Sci {  
    6467
    6568extern int sci0_palette;
    6669
    67 /* (gfx_pic_0.c) The 16 EGA base colors */
     70/** The 16 EGA base colors */
    6871extern Palette* gfx_sci0_image_pal[];
    6972extern gfx_pixmap_color_t gfx_sci0_image_colors[][16];
    7073
    71 /* (gfx_pic_0.c) The 256 interpolated colors (initialized when
    72 ** gfxr_init_pic() is called for the first time, or when gfxr_init_static_palette() is called)
    73 */
     74/**
     75 * The 256 interpolated colors (initialized when gfxr_init_pic() is called
     76 * for the first time, or when gfxr_init_static_palette() is called)
     77 */
    7478extern Palette* gfx_sci0_pic_colors;
    7579
    76 
    7780struct gfxr_pic0_params_t {
    7881        gfx_line_mode_t line_mode; /* one of GFX_LINE_MODE_* */
    7982        gfx_brush_mode_t brush_mode;
    8083};
    8184
     85/** @brief A SCI resource pic */
    8286struct gfxr_pic_t {
    83         int ID; /* pic number (NOT resource ID, just number) */
     87        int ID; /**< pic number (NOT resource ID, just number) */
    8488        gfx_mode_t *mode;
    85         gfx_pixmap_t *visual_map;
    86         gfx_pixmap_t *priority_map;
    87         gfx_pixmap_t *control_map;
    88 
     89        gfx_pixmap_t *visual_map; /**< Visual part of pic */
     90        gfx_pixmap_t *priority_map; /**< Priority map for pic */
     91        gfx_pixmap_t *control_map; /**< Control map for pic */
     92
     93        /**
     94         * @brief Auxiliary map.
     95         * Bit 0: Vis
     96         * Bit 1: Pri
     97         * Bit 2: Ctrl
     98         * Bit 3-5: 'filled' (all three bits are set to 1)
     99         */
    89100        byte aux_map[GFXR_AUX_MAP_SIZE];
    90101
    91         /* Auxiliary map details:
    92         ** Bit 0: Vis
    93         ** Bit 1: Pri
    94         ** Bit 2: Ctrl
    95         ** Bit 3-5: 'filled' (all three bits are set to 1)
    96         */
    97 
    98102        // rect_t bounds;       // unused
    99103
    100         void *undithered_buffer; /* copies visual_map->index_data before dithering */
     104        void *undithered_buffer; /**< copies visual_map->index_data before dithering */
    101105        int undithered_buffer_size;
    102106
    103107        int *priorityTable;
    104108};
    105109
    106 
     110/** A animation loop */
    107111struct gfxr_loop_t {
    108         int cels_nr;
    109         gfx_pixmap_t **cels;
     112        int cels_nr; /**< Number of 'cels' or frames in the animation */
     113        gfx_pixmap_t **cels; /**< Pointer to the pixmaps for the cels */
    110114};
    111115
    112 
     116/** A graphics view */
    113117struct gfxr_view_t {
    114118        int ID;
    115119
    struct gfxr_view_t {  
    122126        int translation[GFX_SCI0_IMAGE_COLORS_NR];
    123127};
    124128
     129/**
     130 * @brief Initializes the static 256 color palette.
     131 */
    125132void gfxr_init_static_palette();
    126 /* Initializes the static 256 color palette
    127 ** Parameters: (void)
    128 ** Returns   : (void)
    129 */
    130 
    131 gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, int sci1);
    132 /* Initializes a gfxr_pic_t for a specific mode
    133 ** Parameters: (gfx_mode_t *) mode: The specific graphics mode
    134 **             (int) ID: The ID to assign to the resulting pixmaps
    135 ** Returns   : (gfxr_pic_t *) The allocated pic resource, or NULL on error.
    136 ** This function allocates memory for use by resource drawer functions.
    137 */
    138133
    139 void gfxr_free_pic(gfxr_pic_t *pic);
    140 /* Uninitializes a pic resource
    141 ** Parameters: (gfxr_pic_t *) pic: The pic to free
    142 ** Returns   : (void)
    143 */
    144 
    145 void gfxr_free_view(gfxr_view_t *view);
    146 /* Frees all memory associated with a view
    147 ** Paremeters: (gfxr_view_t *) view: The view to free
    148 ** Returns   : (void)
    149 */
     134/** @name Resource picture management functions */
     135/** @{ */
    150136
     137/**
     138 * @brief Initializes a gfxr_pic_t for a specific mode.
     139 *
     140 * This function allocates memory for use by resource drawer functions.
     141 *
     142 * @param[in] mode      The specific graphics mode
     143 * @param[in] ID        The ID to assign to the resulting pixmaps
     144 * @param[in] sci1      true if a SCI1 pic, false otherwise
     145 * @return                      The allocated pic resource, or NULL on error.
     146 */
     147gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, bool sci1);
    151148
     149/**
     150 * @brief Uninitializes a pic resource.
     151 *
     152 * @param[in] pic       The pic to free
     153 */
     154void gfxr_free_pic(gfxr_pic_t *pic);
    152155
     156/**
     157 * @brief Frees all memory associated with a view.
     158 *
     159 * @param[in] view      The view to free
     160 */
     161void gfxr_free_view(gfxr_view_t *view);
     162/** @} */
     163/** @name SCI0 resource picture operations */
     164/** @{ */
    153165
    154 /*********************/
    155 /*  SCI0 operations  */
    156 /*********************/
     166/**
     167 * @brief Clears all pic buffers of one pic/
     168 *
     169 * This function should be called before gfxr_draw_pic0, unless cumulative
     170 * drawing is intended
     171 *
     172 * @param[in] pic                       The picture to clear
     173 * @param[in] titlebar_size     How much space to reserve for the title bar
     174 */
     175void gfxr_clear_pic0(gfxr_pic_t *pic, int titlebar_size);
    157176
     177/**
     178 * @brief Draws a pic resource (all formats prior to SCI1.1).
     179 *
     180 * The result is stored in gfxr_visual_map, gfxr_priority_map, and
     181 * gfxr_control_map. The palette entry of gfxr_visual_map is never used.
     182 * Note that the picture will not be drawn dithered; use gfxr_dither_pic0
     183 * for that.
     184 *
     185 * @param[in] pic                               The pic to draw to
     186 * @param[in] fill_normally             If 1, the pic is drawn normally; if 0, all
     187 *                                                              fill operations will fill with black
     188 * @param[in] default_palette   The default palette to use for drawing
     189 * @param[in] size                              Resource size
     190 * @param[in] resource                  Pointer to the resource data
     191 * @param[in] style                             The drawing style
     192 * @param[in] resid                             The resource ID
     193 * @param[in] sci1                              true if SCI1, false otherwise
     194 * @param[in] static_pal                The static palette
     195 * @param[in] portBounds                The bounds of the port being drawn to
     196 */
     197void gfxr_draw_pic01(gfxr_pic_t *pic, int fill_normally,
     198                int default_palette, int size, byte *resource,
     199                gfxr_pic0_params_t *style, int resid, int sci1,
     200                Palette *static_pal, Common::Rect portBounds);
    158201
    159 void gfxr_clear_pic0(gfxr_pic_t *pic, int titlebar_size);
    160 /* Clears all pic buffers of one pic
    161 ** Parameters: (gfxr_pic_t) pic: The picture to clear
    162 **             (int) titlebar_size: How much space to reserve for the title bar
    163 ** Returns   : (void)
    164 ** This function should be called before gfxr_draw_pic0, unless cumulative
    165 ** drawing is intended
    166 */
    167 
    168 
    169 void gfxr_draw_pic01(gfxr_pic_t *pic, int fill_normally, int default_palette,
    170         int size, byte *resource, gfxr_pic0_params_t *style, int resid, int sci1,
    171         Palette *static_pal, Common::Rect portBounds);
    172 /* Draws a pic resource (all formats prior to SCI1.1)
    173 ** Parameters: (gfxr_pic_t *) pic: The pic to draw to
    174 **             (int) fill_normally: If 1, the pic is drawn normally; if 0, all
    175 **                                  fill operations will fill with black
    176 **             (int) default_palette: The default palette to use for drawing
    177 **             (int) size: Resource size
    178 **             (byte *) resource: Pointer to the resource data
    179 **             (gfxr_pic0_params_t *) style: The drawing style
    180 **             (int) resid: The resource ID
    181 **             (int) sci1: Nonzero if SCI1
    182 **             (Palette *) static_pal: The static palette
    183 **             (int) static_pal_nr: Number of entries in static palette
    184 ** Returns   : (void)
    185 ** The result is stored in gfxr_visual_map, gfxr_priority_map, and gfxr_control_map.
    186 ** The palette entry of gfxr_visual_map is never used.
    187 ** Note that the picture will not be drawn dithered; use gfxr_dither_pic0 for that.
    188 */
    189 
    190 void gfxr_draw_pic11(gfxr_pic_t *pic, int fill_normally, int default_palette,
    191         int size, byte *resource, gfxr_pic0_params_t *style, int resid,
    192         Palette *static_pal, Common::Rect portBounds);
    193 /* Draws a pic resource (SCI1.1)
    194 ** Parameters: (gfxr_pic_t *) pic: The pic to draw to
    195 **             (int) fill_normally: If 1, the pic is drawn normally; if 0, all
    196 **                                  fill operations will fill with black
    197 **             (int) default_palette: The default palette to use for drawing
    198 **             (int) size: Resource size
    199 **             (byte *) resource: Pointer to the resource data
    200 **             (gfxr_pic0_params_t *) style: The drawing style
    201 **             (int) resid: The resource ID
    202 **             (Palette *) static_pal: The static palette
    203 **             (int) static_pal_nr: Number of entries in static palette
    204 ** Returns   : (void)
    205 ** The result is stored in gfxr_visual_map, gfxr_priority_map, and gfxr_control_map.
    206 ** The palette entry of gfxr_visual_map is never used.
    207 ** Note that the picture will not be drawn dithered; use gfxr_dither_pic0 for that.
    208 */
     202/**
     203 * @brief Draws a pic resource (SCI1.1).
     204 *
     205 * The result is stored in gfxr_visual_map, gfxr_priority_map, and
     206 * gfxr_control_map. The palette entry of gfxr_visual_map is never used.
     207 * Note that the picture will not be drawn dithered; use gfxr_dither_pic11
     208 * for that.
     209 *
     210 * @param[in] pic                               The pic to draw to
     211 * @param[in] fill_normally             If 1, the pic is drawn normally; if 0, all
     212 *                                                              fill operations will fill with black
     213 * @param[in] default_palette   The default palette to use for drawing
     214 * @param[in] size                              Resource size
     215 * @param[in] resource                  Pointer to the resource data
     216 * @param[in] style                             The drawing style
     217 * @param[in] resid                             The resource ID
     218 * @param[in] static_pal                The static palette
     219 * @param[in] portBounds                Bounds of the port being drawn to
     220 */
     221void gfxr_draw_pic11(gfxr_pic_t *pic, int fill_normally,
     222                int default_palette, int size, byte *resource,
     223                gfxr_pic0_params_t *style, int resid, Palette *static_pal,
     224                Common::Rect portBounds);
    209225
     226/**
     227 * @brief Removes artifacts from a scaled pic.
     228 *
     229 * Using information from the (correctly rendered) src pic, this function
     230 * implements some heuristics to remove artifacts from dest. Must be used
     231 * before dither_pic0 is called, because it operates on the index buffer.
     232 *
     233 * @param[in] dest      The scaled pic
     234 * @param[in] src       An unscaled pic
     235 */
    210236void gfxr_remove_artifacts_pic0(gfxr_pic_t *dest, gfxr_pic_t *src);
    211 /* Removes artifacts from a scaled pic
    212 ** Parameters: (gfxr_pic_t *) dest: The scaled pic
    213 **             (gfxr_pic_t *) src: An unscaled pic
    214 ** Returns   : (void)
    215 ** Using information from the (correctly rendered) src pic, this function implements
    216 ** some heuristics to remove artifacts from dest. Must be used before dither_pic0 is
    217 ** called, because it operates on the index buffer.
    218 */
    219237
     238/**
     239 * @brief Dithers a gfxr_visual_map.
     240 *
     241 * @param[in] pic               The pic to dither
     242 * @param[in] mode              One of GFXR_DITHER_MODE
     243 * @param[in] pattern   One of GFXR_DITHER_PATTERN
     244 */
    220245void gfxr_dither_pic0(gfxr_pic_t *pic, int mode, int pattern);
    221 /* Dithers a gfxr_visual_map
    222 ** Parameters: (gfxr_pic_t *) pic: The pic to dither
    223 **             (int) mode: One of GFXR_DITHER_MODE
    224 **             (int) pattern: One of GFXR_DITHER_PATTERN
    225 ** Returns   : (void)
    226 */
    227246
     247/**
     248 * @brief Calculates a SCI0 view.
     249 *
     250 * @param[in] id                Resource ID of the view
     251 * @param[in] resource  Pointer to the resource to read
     252 * @param[in] size              Size of the resource
     253 * @param[in] palette   The palette to use
     254 * @return                              The resulting view
     255 */
    228256gfxr_view_t *gfxr_draw_view0(int id, byte *resource, int size, int palette);
    229 /* Calculates an SCI0 view
    230 ** Parameters: (int) id: Resource ID of the view
    231 **             (byte *) resource: Pointer to the resource to read
    232 **             (int) size: Size of the resource
    233 **             (int) palette: The palette to use
    234 ** Returns   : (gfxr_view_t *) The resulting view
    235 */
    236 
    237 gfx_pixmap_t *gfxr_draw_cursor(int id, byte *resource, int size, bool isSci01);
    238 /* Calculates n SCI cursor
    239 ** Parameters: (int) id: The cursor's resource ID
    240 **             (byte *) resource: Pointer to the resource data
    241 **             (int) size: Resource size
    242 **             (bool) isSci01: Set to true to load a SCI1 cursor
    243 ** Returns   : (gfx_pixmap_t *) A newly allocated pixmap containing an index
    244 **                               color representation of the cursor
    245 */
    246 
    247 /*********************/
    248 /*  SCI1 operations  */
    249 /*********************/
    250257
     258/**
     259 * @brief Calculates a SCI cursor.
     260 *
     261 * @param[in] id                The cursor's resource ID
     262 * @param[in] resource  Pointer to the resource data
     263 * @param[in] size              Resource size
     264 * @param[in] isSci01   Set to true to load a SCI1 cursor
     265 * @return                              A newly allocated pixmap containing an index color
     266 *                                              representation of the cursor
     267 */
     268gfx_pixmap_t *gfxr_draw_cursor(int id, byte *resource, int size,
     269                bool isSci01);
     270/** @} */
     271
     272
     273/** @name SCI1/1.1 resource picture operations */
     274/** @{ */
     275
     276/**
     277 * @brief Reads an SCI1 palette.
     278 *
     279 * @param[in] id                Resource ID for the palette (or the view it was
     280 *                                              found in)
     281 * @param[in] resource  Source data
     282 * @param[in] size              Size of the memory block pointed to by resource
     283 * @return                              Palette with the colors
     284 */
    251285Palette *gfxr_read_pal1(int id, byte *resource, int size);
    252 /* Reads an SCI1 palette
    253 ** Parameters: (int) id: Resource ID for the palette (or the view it was found in)
    254 **             (int *) colors_nr: Pointer to the variable the number of colors
    255 **                                will be stored in
    256 **             (byte *) resource: Source data
    257 **             (int) size: Size of the memory block pointed to by resource
    258 ** Returns   : (Palette *) *colors_nr Palette with the colors
    259 */
    260286
     287/**
     288 * @brief Reads an SCI1 palette.
     289 *
     290 * @param[in] file      Palette file
     291 * @return                      Palette with the colors
     292 */
    261293Palette *gfxr_read_pal1_amiga(Common::File &file);
    262 /* Reads an SCI1 palette
    263 ** Parameters: (int *) colors_nr: Pointer to the variable the number of colors
    264 **                                will be stored in
    265 **             (FILE *) f: Palette file
    266 ** Returns   : (Palette *) Palette with the colors
    267 */
    268294
     295/**
     296 * @brief Reads an SCI1.1 palette.
     297 *
     298 * @param[in] id                Resource ID for the palette (or the view it was
     299 *                                              found in)
     300 * @param[in] resource  Source data
     301 * @param[in] size              Size of the memory block pointed to by resource
     302 * @return                              Palette with the colors
     303 */
    269304Palette *gfxr_read_pal11(int id, byte *resource, int size);
    270 /* Reads an SCI1.1 palette
    271 ** Parameters: (int) id: Resource ID for the palette (or the view it was found in)
    272 **             (int *) colors_nr: Pointer to the variable the number of colors
    273 **                                will be stored in
    274 **             (byte *) resource: Source data
    275 **             (int) size: Size of the memory block pointed to by resource
    276 ** Returns   : (Palette *) Palette with the colors
    277 */
    278305
     306/**
     307 * @brief Calculates an SCI1 view.
     308 *
     309 * @param[in] id                        Resource ID of the view
     310 * @param[in] resource          Pointer to the resource to read
     311 * @param[in] size                      Size of the resource
     312 * @param[in] static_pal        The static palette
     313 * @param[in] isSci11           true if SCI1.1, false otherwise
     314 * @return                                      The resulting view
     315 */
    279316gfxr_view_t *gfxr_draw_view1(int id, byte *resource, int size, Palette *static_pal, bool isSci11);
    280 /* Calculates an SCI1 view
    281 ** Parameters: (int) id: Resource ID of the view
    282 **             (byte *) resource: Pointer to the resource to read
    283 **             (int) size: Size of the resource
    284 **             (Palette *) static_pal: The static palette
    285 **             (int) static_pal_nr: Number of entries in static palette
    286 ** Returns   : (gfxr_view_t *) The resulting view
    287 */
    288317
    289318gfx_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);
    290 
     319/** @} */
    291320
    292321} // End of namespace Sci
    293322
  • engines/sci/gfx/gfx_state_internal.h

    diff --git a/engines/sci/gfx/gfx_state_internal.h b/engines/sci/gfx/gfx_state_internal.h
    index d03c5e9..0306c94 100644
    a b  
    3434
    3535namespace Sci {
    3636
    37 #define GFXW_FLAG_VISIBLE (1<<0)
    38 #define GFXW_FLAG_OPAQUE (1<<1)
    39 #define GFXW_FLAG_CONTAINER (1<<2)
    40 #define GFXW_FLAG_DIRTY (1<<3)
    41 #define GFXW_FLAG_TAGGED (1<<4)
    42 #define GFXW_FLAG_MULTI_ID (1<<5) /**< Means that the ID used herein may be used more than once, i.e. is not unique */
    43 #define GFXW_FLAG_IMMUNE_TO_SNAPSHOTS (1<<6) /**< Snapshot restoring doesn't kill this widget, and +5 bonus to saving throws vs. Death Magic */
    44 #define GFXW_FLAG_NO_IMPLICIT_SWITCH (1<<7) /**< Ports: Don't implicitly switch to this port when disposing windows */
     37enum gfxw_flag_t {
     38        GFXW_FLAG_VISIBLE                               = (1<<0),
     39        GFXW_FLAG_OPAQUE                                = (1<<1),
     40        GFXW_FLAG_CONTAINER                             = (1<<2),
     41        GFXW_FLAG_DIRTY                                 = (1<<3),
     42        GFXW_FLAG_TAGGED                                = (1<<4),
     43        GFXW_FLAG_MULTI_ID                              = (1<<5), /**< Means that the ID used herein may be used more than once, i.e. is not unique */
     44        GFXW_FLAG_IMMUNE_TO_SNAPSHOTS   = (1<<6), /**< Snapshot restoring doesn't kill this widget, and +5 bonus to saving throws vs. Death Magic */
     45        GFXW_FLAG_NO_IMPLICIT_SWITCH    = (1<<7) /**< Ports: Don't implicitly switch to this port when disposing windows */
     46};
    4547
    4648struct gfxw_snapshot_t {
    4749        int serial; /**< The first serial number to kill */
    struct GfxPort;  
    8284
    8385typedef int gfxw_bin_op(GfxWidget *, GfxWidget *);
    8486
     87/** @brief SCI graphics widget */
    8588struct GfxWidget {
    8689public:
    8790        int _magic; /**< Extra check after typecasting */
    public:  
    101104
    102105        /**
    103106         * The widget automatically removes itself from its owner, if it has one.
    104          * Deleting a container will recursively free all of its
    105          * contents.
     107         * Deleting a container will recursively free all of its contents.
    106108         */
    107109        virtual ~GfxWidget();
    108110
    109111        /**
    110          * Draws the widget.
     112         * @brief Draws the widget.
    111113         *
    112          * The widget is drawn iff it is flagged as dirty. Invoking this operation on
    113          * a container widget will recursively draw all of its contents.
     114         * The widget is drawn iff it is flagged as dirty. Invoking this operation
     115         * on a container widget will recursively draw all of its contents.
    114116         *
    115          * @param pos   The position to draw to (added to the widget's  internal position)
     117         * @param[in] pos       The position to draw to (added to the widget's
     118         *                                      internal position)
    116119         */
    117120        virtual int draw(const Common::Point &pos) = 0;
    118121
    119122        /**
    120          * Tags the specified widget.
     123         * @brief Tags the specified widget.
    121124         *
    122          * If invoked on a container widget, this will also tag all of the container's
    123          * contents (but not the contents' contents!)
    124          * FIXME: Actually, the code in GfxContainer::tag contradicts the last claim!
     125         * If invoked on a container widget, this will also tag all of the
     126         * container's contents (but not the contents' contents!)
     127         * FIXME: Actually, the code in GfxContainer::tag contradicts the last
     128         * claim!
    125129         */
    126130        virtual void tag() {
    127131                _flags |= GFXW_FLAG_TAGGED;
    128132        }
    129133
    130134        /**
    131          * Prints a string representation of the widget with sciprintf.
     135         * @brief Prints a string representation of the widget with sciprintf.
    132136         *
    133          * Will recursively print all of the widget's contents if the widget contains
    134          * further sub-widgets
     137         * Will recursively print all of the widget's contents if the widget
     138         * contains further sub-widgets
    135139         *
    136          * @param indentation   Number of double spaces to indent
     140         * @param[in] indentation       Number of double spaces to indent
    137141         */
    138142        virtual void print(int indentation) const;
    139143
    140144        /**
    141          * Compares two comparable widgets by their screen position.
     145         * @brief Compares two comparable widgets by their screen position.
    142146         *
    143147         * This comparison only applies to some widgets; compare_to(a,a)=0 is not
    144148         * guaranteed. It may be used for sorting for all widgets.
    145149         *
    146          * @param other other widget
    147          * @return <0, 0, or >0 if other is, respectively, less than, equal
    148          *          to, or greater than self
     150         * @param other The other widget
     151         * @return              <0, 0, or >0 if other is, respectively, less than, equal
     152         *                              to, or greater than self
    149153         */
    150154        gfxw_bin_op *compare_to;
    151155
    152156        /**
    153          * Compares two compareable widgets for equality.
     157         * @brief Compares two compareable widgets for equality.
    154158         *
    155          * This operation checks whether two widgets describe the same graphical data.
    156          * It is used to determine whether a new widget should be discarded because it
    157          * describes the same graphical data as an old widget that has already been
    158          * drawn. For lists, it also checks whether all contents are in an identical
    159          * order.
     159         * This operation checks whether two widgets describe the same graphical
     160         * data. It is used to determine whether a new widget should be discarded
     161         * because it describes the same graphical data as an old widget that has
     162         * already been drawn. For lists, it also checks whether all contents are
     163         * in an identical order.
    160164         *
    161          * @param other other widget
    162          * @return false if the widgets are not equal, true if they match
     165         * @param[in] other     The other widget
     166         * @return                      false if the widgets are not equal, true if they match
    163167         */
    164168        gfxw_bin_op *equals;
    165169
    166170        /**
    167          * Determine whether other should replace this even though they are equivalent.
     171         * @brief Determine whether other should replace this even though they are
     172         * equivalent.
    168173         *
    169174         * When 'equals' returns true, this means that no new widget will be added.
    170175         * However, in some cases newer widgets may contain information that should
    171          * cause the older widget to be removed nonetheless; this is indicated by this
    172          * function.
     176         * cause the older widget to be removed nonetheless; this is indicated by
     177         * this function.
    173178         *
    174          * @param other other widget
    175          * @return false if this should be kept, true if this should be replaced by the 'other'
     179         * @param[in] other     The other widget
     180         * @return                      false if this should be kept, true if this should be
     181         *                                      replaced by the 'other'
    176182         */
    177183        gfxw_bin_op *should_replace;
    178184
    179185        /**
    180          * Tests whether drawing this after other would reduce all traces of other.
     186         * @brief Tests whether drawing this after other would reduce all traces of
     187         * other.
    181188         *
    182          * /a superarea_of b <=> for each pixel of b there exists an opaque pixel in a at the same location
     189         * /a superarea_of b <=> for each pixel of b there exists an opaque pixel
     190         * in a at the same location
    183191         *
    184          * @param other the widget to compare for containment
    185          * @return      true if this is superarea_of other, false otherwise
     192         * @param[in] other     The widget to compare for containment
     193         * @return                      true if this is superarea_of other, false otherwise
    186194         */
    187195        gfxw_bin_op *superarea_of;
    188196
    189197        /**
    190          * Sets the visual for the widget
    191          * This function is called by container->add() and need not be invoked explicitly.
    192          * It also makes sure that dirty rectangles are passed to parent containers.
     198         * @brief Sets the visual for the widget
     199         *
     200         * This function is called by container->add() and need not be invoked
     201         * explicitly. It also makes sure that dirty rectangles are passed to
     202         * parent containers.
     203         *
     204         * @param[in] visual    GfxVisual to set for the widget
    193205         */
    194         virtual int setVisual(GfxVisual *);
     206        virtual int setVisual(GfxVisual *visual);
    195207
    196208//protected:
    197209        void printIntern(int indentation) const;
    public:  
    200212
    201213
    202214#define GFXW_IS_BOX(widget) ((widget)->_type == GFXW_BOX)
     215/** @brief SCI box widget */
    203216struct GfxBox : public GfxWidget {
    204217        gfx_color_t _color1, _color2;
    205218        gfx_box_shade_t _shadeType;
    public:  
    213226
    214227
    215228#define GFXW_IS_PRIMITIVE(widget) ((widget)->_type == GFXW_RECT || (widget)->_type == GFXW_LINE)
     229/** @brief SCI graphics primitive */
    216230struct GfxPrimitive : public GfxWidget {
    217231        gfx_color_t _color;
    218232        gfx_line_mode_t _lineMode;
    public:  
    227241
    228242#define GFXW_IS_VIEW(widget) ((widget)->_type == GFXW_VIEW || (widget)->_type == GFXW_STATIC_VIEW \
    229243                              || (widget)->_type == GFXW_DYN_VIEW || (widget)->_type == GFXW_PIC_VIEW)
     244/** @brief SCI graphics view */
    230245struct GfxView  : public GfxWidget {
    231246        Common::Point _pos; /**< Implies the value of 'bounds' in GfxWidget */
    232247        gfx_color_t _color;
    public:  
    242257};
    243258
    244259#define GFXW_IS_DYN_VIEW(widget) ((widget)->_type == GFXW_DYN_VIEW || (widget)->_type == GFXW_PIC_VIEW)
     260/** @brief SCI dynamic view */
    245261struct GfxDynView : public GfxView {
    246262        /* FIXME: This code is specific to SCI */
    247263        rect_t draw_bounds; /* The correct position to draw to */
    public:  
    265281
    266282
    267283#define GFXW_IS_TEXT(widget) ((widget)->_type == GFXW_TEXT)
     284/** @brief SCI text widget */
    268285struct GfxText : public GfxWidget {
    269286        int _font;
    270287        int lines_nr, lineheight, lastline_width;
    typedef int gfxw_unary_container_op(GfxContainer *);  
    293310typedef int gfxw_container_op(GfxContainer *, GfxWidget *);
    294311typedef int gfxw_rect_op(GfxContainer *, rect_t, int);
    295312
    296 
     313/** @brief SCI container widget */
    297314struct GfxContainer : public GfxWidget {
    298315        rect_t zone; /**< The writeable zone (absolute) for contained objects */
    299316        DirtyRectList _dirtyRects; /**< List of dirty rectangles */
    public:  
    324341
    325342#define GFXW_IS_LIST(widget) ((widget)->_type == GFXW_LIST || (widget)->_type == GFXW_SORTED_LIST)
    326343#define GFXW_IS_SORTED_LIST(widget) ((widget)->_type == GFXW_SORTED_LIST)
    327 
     344/** @brief SCI graphics list */
    328345struct GfxList : public GfxContainer {
    329346public:
    330347        GfxList(rect_t area, bool sorted);
    public:  
    334351};
    335352
    336353#define GFXW_IS_VISUAL(widget) ((widget)->_type == GFXW_VISUAL)
     354/** @brief SCI graphic visual */
    337355struct GfxVisual : public GfxContainer {
    338356        Common::Array<GfxPort *> _portRefs; /**< References to ports */
    339357        int _font; /**< Default font */
    public:  
    353371};
    354372
    355373#define GFXW_IS_PORT(widget) ((widget)->_type == GFXW_PORT)
     374/** @brief SCI graphics port */
    356375struct GfxPort : public GfxContainer {
    357376        GfxList *_decorations; /**< optional window decorations - drawn before the contents */
    358377        GfxWidget *port_bg; /**< Port background widget or NULL */
    struct GfxPort : public GfxContainer {  
    366385        byte gray_text; /**< Whether text is 'grayed out' (dithered) */
    367386
    368387public:
    369         /* Creates a new port widget with the default settings
    370         ** Paramaters: (GfxVisual *) visual: The visual the port is added to
    371         **             (GfxPort *) predecessor: The port's predecessor
    372         **             (rect_t) area: The screen area covered by the port (absolute position)
    373         **             (gfx_color_t) fgcolor: Foreground drawing color
    374         **             (gfx_color_t) bgcolor: Background color
    375         ** A port differentiates itself from a list in that it contains additional information,
    376         ** and an optional title (stored in a display list).
    377         ** Ports are assigned implicit IDs identifying their position within the port stack.
    378         */
     388        /**
     389         * @brief Creates a new port widget with the default settings
     390         *
     391         * A port differentiates itself from a list in that it contains additional
     392         * information, and an optional title (stored in a display list).
     393         * Ports are assigned implicit IDs identifying their position within the
     394         * port stack.
     395         *
     396         * @param[in] visual            The visual the port is added to
     397         * @param[in] area                      The screen area covered by the port (absolute
     398         *                                                      position)
     399         * @param[in] fgcolor           Foreground drawing color
     400         * @param[in] bgcolor           Background color
     401         */
    379402        GfxPort(GfxVisual *visual, rect_t area, gfx_color_t fgcolor, gfx_color_t bgcolor);
    380403        ~GfxPort();
    381404
  • engines/sci/gfx/gfx_system.h

    diff --git a/engines/sci/gfx/gfx_system.h b/engines/sci/gfx/gfx_system.h
    index 3922b21..aa39d7d 100644
    a b namespace Sci {  
    3636#define GFX_DEBUG
    3737
    3838/* General output macros */
    39 #  define GFXERROR sciprintf("GFX Error: %s, L%d:", __FILE__, __LINE__); error
     39#define GFXERROR sciprintf("GFX Error: %s, L%d:", __FILE__, __LINE__); error
    4040
    4141/***********************/
    4242/*** Data structures ***/
    namespace Sci {  
    5050** enabled  */
    5151#define GFX_MODE_FLAG_REVERSE_ALPHA  (1<<1)
    5252
    53 /** Graphics mode description */
    54 struct gfx_mode_t {
     53/** @brief Graphics mode description
     54 *
     55 * Color masks:
     56 * Each of the mask/shift pairs describe where the corresponding color
     57 * values are stored for the described mode. Internally, color
     58 * calculations are done by using 32 bit values for r, g, b, a. After
     59 * the internal values have been calculated, they are shifted RIGHT
     60 * by the xxx_shift amount described above, then ANDed with the
     61 * corresponding color mask; finally, all three results are ORred to-
     62 * gether. The alpha values are used as appropriate; if alpha_mask is
     63 * zero, then images use a special alpha map.
     64 */
    5565
    56         int xfact, yfact; /* Horizontal and vertical scaling factors */
    57         int xsize, ysize; /* Horizontal and vertical size */
    58         int bytespp; /* Bytes per pixel */
     66struct gfx_mode_t {
    5967
    60         uint32 flags; /* GFX_MODE_FLAG_* Flags- see above */
     68        int xfact, yfact; /**< Horizontal and vertical scaling factors */
     69        int xsize, ysize; /**< Horizontal and vertical size */
     70        int bytespp; /**< Bytes per pixel */
    6171
     72        uint32 flags; /**< GFX_MODE_FLAG_* Flags- see above */
    6273
    63         Palette *palette; // Palette or NULL to indicate non-palette mode.
    64                           // Palette mode is only supported for bytespp = 1
     74        /**
     75         * Palette or NULL to indicate non-palette mode.
     76         * Palette mode is only supported for bytespp = 1
     77         */
     78        Palette *palette;
    6579
    66         /* Color masks */
    6780        uint32 red_mask, green_mask, blue_mask, alpha_mask;
    6881        short red_shift, green_shift, blue_shift, alpha_shift;
    69 
    70         /* Each of the mask/shift pairs describe where the corresponding color
    71         ** values are stored for the described mode. Internally, color
    72         ** calculations are done by using 32 bit values for r, g, b, a. After
    73         ** the internal values have been calculated, they are shifted RIGHT
    74         ** by the xxx_shift amount described above, then ANDed with the
    75         ** corresponding color mask; finally, all three results are ORred to-
    76         ** gether. The alpha values are used as appropriate; if alpha_mask is
    77         ** zero, then images use a special alpha map.  */
    78 
    7982};
    8083
    8184
    8285
    8386#define GFX_COLOR_INDEX_UNMAPPED -1
    8487
    85 /** Pixmap-specific color entries */
     88/** @brief Pixmap-specific color entries */
    8689struct  gfx_pixmap_color_t{
    87         int global_index; /* Global index color or GFX_COLOR_INDEX_UNMAPPED. */
    88         uint8 r, g, b; /* Real color */
     90        int global_index; /**< Global index color or GFX_COLOR_INDEX_UNMAPPED. */
     91        uint8 r, g, b; /**< Real color */
    8992};
    9093
    91 /** Full color */
     94/** @brief Full color */
    9295struct gfx_color_t {
    9396        PaletteEntry visual;
    94         uint8 alpha; /* transparency = (1-opacity) */
     97        uint8 alpha; /**< transparency = (1-opacity) */
    9598        int8 priority, control;
    96         byte mask; /* see mask values below */
     99        byte mask; /**< see mask values below */
    97100};
    98101
    99102
    100103// TODO: Replace rect_t by Common::Rect
    101 /** Rectangle description */
     104/** @brief Rectangle description */
    102105struct rect_t {
    103106        int x, y;
    104107        int width, height; /* width, height: (x,y,width,height)=(5,5,1,1) occupies 1 pixel */
    105108};
    106109
    107 /* Generates a rect_t from index data
    108 ** Parameters: (int x int) x,y: Upper left point of the rectangle
    109 **             (int x int) width, height: Horizontal and vertical extension of the rectangle
    110 ** Returns   : (rect_t) A rectangle matching the supplied parameters
    111 */
     110/**
     111 * @brief Generates a rect_t from index data
     112 *
     113 * @param[in] x                 Left side of the rectangle
     114 * @param[in] y                 Top side of the rectangle
     115 * @param[in] width             Horizontal extent of the rectangle
     116 * @param[in] height    Verical extent of the rectangle
     117 * @return                              A rectangle matching the supplied parameters
     118 */
    112119static inline rect_t gfx_rect(int x, int y, int width, int height) {
    113120        rect_t rect;
    114121
    static inline rect_t gfx_rect(int x, int y, int width, int height) {  
    120127        return rect;
    121128}
    122129
    123 // Temporary helper functions to ease the transition from rect_t to Common::Rect
     130/**
     131 * @brief Temporary helper function to ease the transition from rect_t to Common::Rect
     132 */
    124133static inline rect_t toSCIRect(Common::Rect in) {
    125134        return gfx_rect(in.left, in.top, in.width(), in.height());
    126135}
    127136
     137/**
     138 * @brief Temporary helper function to ease the transition from rect_t to Common::Rect
     139 */
    128140static inline Common::Rect toCommonRect(rect_t in) {
    129141        return Common::Rect(in.x, in.y, in.x + in.width, in.y + in.height);
    130142}
    static inline Common::Rect toCommonRect(rect_t in) {  
    133145
    134146#define OVERLAP(a, b, z, zl) (a.z >= b.z && a.z < (b.z + b.zl))
    135147
    136 /* Determines whether two rects overlap
    137 ** Parameters: (rect_t x rect_t) a,b: The two rect_ts to check for overlap
    138 ** Returns   : (int) 1 if they overlap, 0 otherwise
    139 */
     148/**
     149 * @brief Determines whether two rects overlap
     150 *
     151 * @param[in] a First rect to check for overlap
     152 * @param[in] b Second rect to check for overlap
     153 * @return              1 if they overlap, 0 otherwise
     154 */
    140155static inline int gfx_rects_overlap(rect_t a, rect_t b) {
    141156        return (OVERLAP(a, b, x, width) || OVERLAP(b, a, x, width)) && (OVERLAP(a, b, y, height) || OVERLAP(b, a, y, height));
    142157}
    extern rect_t gfx_rect_fullscreen;  
    150165
    151166#define GFX_PIC_COLORS 256
    152167
    153 #define GFX_PIXMAP_FLAG_SCALED_INDEX      (1<<0) /* Index data is scaled already */
    154 #define GFX_PIXMAP_FLAG_INSTALLED         (1<<2) /* Pixmap has been registered */
    155 #define GFX_PIXMAP_FLAG_PALETTIZED        (1<<6) /* Indicates a palettized view */
     168#define GFX_PIXMAP_FLAG_SCALED_INDEX    (1<<0) /* Index data is scaled already */
     169#define GFX_PIXMAP_FLAG_INSTALLED               (1<<2) /* Pixmap has been registered */
     170#define GFX_PIXMAP_FLAG_PALETTIZED              (1<<6) /* Indicates a palettized view */
    156171
    157172#define GFX_PIXMAP_COLOR_KEY_NONE -1 /* No transpacency colour key */
    158173#define GFX_CURSOR_TRANSPARENT 255 // Cursor colour key
    159174
    160 struct gfx_pixmap_t { /* gfx_pixmap_t: Pixel map */
     175/** @brief Pixel map */
     176struct gfx_pixmap_t {
    161177
    162         /*** Meta information ***/
    163         int ID; /* Resource ID, or GFX_RESID_NONE for anonymous graphical data */
    164         short loop, cel; /* loop and cel number for views */
     178        /** @name Meta information
     179         * @{*/
     180        int ID; /**< Resource ID, or GFX_RESID_NONE for anonymous graphical data */
     181        short loop; /**< loop number for view */
     182        short cel;      /**< cel number for view */
     183        /** @}*/
    165184
    166 
    167         /*** Color map ***/
     185        /** @name Color map
     186         * @{*/
    168187        Palette *palette;
    169         int colors_nr() const { return palette ? palette->size() : 0; }
    170                                     /* color entries, or NULL if the
    171                                     ** default palette is to be used.
    172                                     ** A maximum of 255 colors is allowed; color
    173                                     ** index 0xff is reserved for transparency.
    174                                     ** As a special exception, 256 colors are
    175                                     ** allowed for background pictures (which do
    176                                     ** not use transparency)
    177                                     */
    178         uint32 flags;
    179 
    180         /*** Hot spot ***/
    181         int xoffset, yoffset; /* x and y coordinates of the 'hot spot' (unscaled) */
    182188
    183         /*** Index data ***/
    184         int index_width, index_height; /* width and height of the indexed original image */
    185         byte *index_data; /* Color-index data, or NULL if read from an
    186                           ** external source
    187                           */
    188 
    189         /*** Drawable data ***/
    190         int width, height; /* width and height of the actual image */
    191         int data_size; /* Amount of allocated memory */
    192         byte *data; /* Drawable data, or NULL if not converted.  */
    193 
    194         byte *alpha_map; /* Byte map with alpha values. It is used only if the
    195                          ** graphics mode's alpha_mask is zero.
    196                          */
     189        /**
     190         * color entries, or NULL if the default palette is to be used. A maximum
     191         * of 255 colors is allowed; color index 0xff is reserved for transparency.
     192         * As a special exception, 256 colors are allowed for background pictures
     193         * (which do not use transparency)
     194         */
     195        int colors_nr() const { return palette ? palette->size() : 0; }
    197196
    198         int color_key;
    199         int palette_revision; // Revision of palette at the time data was generated
     197        uint32 flags;
     198        /* @} */
     199
     200        /** @name Hot spot
     201         * x and y coordinates of the 'hot spot' (unscaled)
     202         * @{*/
     203        int xoffset, yoffset;
     204        /** @} */
     205
     206        /** @name Index data
     207         * @{
     208         */
     209        int index_width; /**< width of the indexed original image */
     210        int index_height; /**< height of the indexed original image */
     211        byte *index_data; /**< Color-index data, or NULL if read from an external source */
     212        /** @} */
     213
     214        /** @name Drawable data
     215         * @{
     216         */
     217        int width; /**< width of the actual image */
     218        int height; /**< height of the actual image */
     219        int data_size; /**< Amount of allocated memory */
     220        byte *data; /**< Drawable data, or NULL if not converted.  */
     221
     222        byte *alpha_map; /**< Byte map with alpha values. It is used only if the graphics mode's alpha_mask is zero. */
     223
     224        int color_key; /**< The color to make transparent */
     225        int palette_revision; /**< Revision of palette at the time data was generated */
     226        /** @} */
    200227};
    201228
    202229
    203230
    204 /***********************/
    205 /*** Constant values ***/
    206 /***********************/
    207231
    208 /* Return values */
     232/** @name Constant values
     233 * @{ */
     234
     235/** @brief Return values */
    209236enum gfx_return_value_t {
    210         GFX_OK = 0, /* Indicates "operation successful" */
    211         GFX_ERROR = -1, /* Indicates "operation failed" */
    212         GFX_FATAL = -2
    213         /* Fatal error: Used by graphics drivers to indicate that they were unable to
    214         ** do anything useful
    215         */
     237        GFX_OK = 0,             /**< Indicates "operation successful" */
     238        GFX_ERROR = -1, /**< Indicates "operation failed" */
     239        GFX_FATAL = -2  /**< Fatal error: Used by graphics drivers to indicate
     240                                        that they were unable to do anything useful */
    216241};
    217242
    218 
    219 enum gfx_map_mask_t {/* Map masks */
     243/** @brief Map masks */
     244enum gfx_map_mask_t {
    220245        GFX_MASK_NONE = 0,
    221246        GFX_MASK_VISUAL = 1,
    222247        GFX_MASK_PRIORITY = 2,
    223248        GFX_MASK_CONTROL = 4
    224249};
    225250
    226 /* 'no priority' mode */
     251/** @brief 'no priority' mode */
    227252enum {
    228253        GFX_NO_PRIORITY = -1
    229254};
    230255
    231 /* Text alignment values */
    232 
     256/** @brief Text alignment values */
    233257enum gfx_alignment_t {
    234258        ALIGN_RIGHT = -1,
    235259        ALIGN_TOP = -1,
    enum gfx_alignment_t {  
    240264
    241265
    242266enum gfx_line_mode_t {
    243         GFX_LINE_MODE_CORRECT, /* Scaled separately */
    244         GFX_LINE_MODE_FAST,    /* Scaled by (xfact+yfact)/2 */
    245         GFX_LINE_MODE_FINE    /* Always drawn at width 1 */
     267        GFX_LINE_MODE_CORRECT,  /**< Scaled separately */
     268        GFX_LINE_MODE_FAST,             /**< Scaled by (xfact+yfact)/2 */
     269        GFX_LINE_MODE_FINE              /**< Always drawn at width 1 */
    246270};
    247271
    248272enum gfx_brush_mode_t {
    249         GFX_BRUSH_MODE_SCALED, /* Just scale the brush pixels */
    250         GFX_BRUSH_MODE_ELLIPSES, /* Replace pixels with ellipses */
    251         GFX_BRUSH_MODE_RANDOM_ELLIPSES, /* Replace pixels with ellipses moved and re-scaled randomly */
    252         GFX_BRUSH_MODE_MORERANDOM /* Distribute randomly */
     273        GFX_BRUSH_MODE_SCALED,                  /**< Just scale the brush pixels */
     274        GFX_BRUSH_MODE_ELLIPSES,                /**< Replace pixels with ellipses */
     275        GFX_BRUSH_MODE_RANDOM_ELLIPSES, /**< Replace pixels with ellipses moved and re-scaled randomly */
     276        GFX_BRUSH_MODE_MORERANDOM               /**< Distribute randomly */
    253277};
    254278
    255279
    enum gfx_line_style_t {  
    260284
    261285
    262286enum gfx_rectangle_fill_t {
    263         GFX_SHADE_FLAT, /* Don't shade */
    264         GFX_SHADE_VERTICALLY, /* Shade vertically */
    265         GFX_SHADE_HORIZONTALLY /* Shade horizontally */
     287        GFX_SHADE_FLAT,                 /**< Don't shade */
     288        GFX_SHADE_VERTICALLY,   /**< Shade vertically */
     289        GFX_SHADE_HORIZONTALLY  /**< Shade horizontally */
    266290};
    267291
    268292
    269293enum gfx_color_mode_t {
    270         GFX_COLOR_MODE_AUTO = 0, /* Auto-detect- handled by the gfxop library */
    271         GFX_COLOR_MODE_INDEX = 1, /* Index mode */
    272         GFX_COLOR_MODE_HIGH = 2, /* High color mode (15bpp or 16 bpp) */
    273         GFX_COLOR_MODE_TRUE = 4 /* True color mode (24 bpp padded to 32 bpp) */
     294        GFX_COLOR_MODE_AUTO = 0,        /**< Auto-detect- handled by the gfxop library */
     295        GFX_COLOR_MODE_INDEX = 1,       /**< Index mode */
     296        GFX_COLOR_MODE_HIGH = 2,        /**< High color mode (15bpp or 16 bpp) */
     297        GFX_COLOR_MODE_TRUE = 4         /**< True color mode (24 bpp padded to 32 bpp) */
    274298};
     299/** @} */
    275300
    276301} // End of namespace Sci
    277302
  • engines/sci/gfx/gfx_tools.h

    diff --git a/engines/sci/gfx/gfx_tools.h b/engines/sci/gfx/gfx_tools.h
    index 8582dfa..bbf82e6 100644
    a b  
    2323 *
    2424 */
    2525
    26 /* SCI graphics subsystem helper functions */
    27 
    28 
    2926#ifndef SCI_GFX_GFX_TOOLS_H
    3027#define SCI_GFX_GFX_TOOLS_H
    3128
     
    3633
    3734namespace Sci {
    3835
     36/** @name SCI graphics subsystem helper functions */
     37/** @{ */
     38
    3939enum gfx_xlate_filter_t {
    4040        GFX_XLATE_FILTER_NONE,
    4141        GFX_XLATE_FILTER_LINEAR,
    4242        GFX_XLATE_FILTER_TRILINEAR
    4343};
    4444
     45/**
     46 * @brief Allocates a new gfx_mode_t structure with the specified parameters
     47 *
     48 * @param[in] xfact             Horizontal scaling factors
     49 * @param[in] yfact             Vertical scaling factors
     50 * @param[in] format    Pixel format description
     51 * @param[in] palette   Number of palette colors, 0 if we're not in palette mode
     52 * @param[in] flags             GFX_MODE_FLAG_* values ORred together, or just 0
     53 * @return                              A newly allocated gfx_mode_t structure
     54 */
    4555gfx_mode_t *gfx_new_mode(int xfact, int yfact, const Graphics::PixelFormat &format, Palette *palette, int flags);
    46 /* Allocates a new gfx_mode_t structure with the specified parameters
    47 ** Parameters: (int x int) xfact x yfact: Horizontal and vertical scaling factors
    48 **             (Graphics::PixelFormat) format: pixel format description
    49 **             (int) palette: Number of palette colors, 0 if we're not in palette mode
    50 **             (int) flags: GFX_MODE_FLAG_* values ORred together, or just 0
    51 ** Returns   : (gfx_mode_t *) A newly allocated gfx_mode_t structure
    52 */
    53 
    5456
     57/**
     58 * @brief Clips a rect_t
     59 *
     60 * @param[in] box       Pointer to the box to clip
     61 * @param[in] maxx      Maximum allowed width
     62 * @param[in] maxy      Maximum allowed height
     63 */
    5564void gfx_clip_box_basic(rect_t *box, int maxx, int maxy);
    56 /* Clips a rect_t
    57 ** Parameters: (rect_t *) box: Pointer to the box to clip
    58 **             (int x int) maxx, maxy: Maximum allowed width and height
    59 ** Returns   : (void)
    60 */
    61 
    6265
     66/**
     67 * @brief Frees all memory allocated by a mode structure
     68 * @param[in] mode      The mode to free
     69 */
    6370void gfx_free_mode(gfx_mode_t *mode);
    64 /* Frees all memory allocated by a mode structure
    65 ** Parameters: (gfx_mode_t *) mode: The mode to free
    66 ** Returns   : (void)
    67 */
    68 
    6971
     72/**
     73 * @brief Creates a new pixmap structure
     74 *
     75 * The following fiels are initialized:
     76 * ID, loop, cel, index_width, index_height, xl, yl, data <- NULL,
     77 * alpha_map <- NULL, internal.handle <- 0, internal.info <- NULL,
     78 * colors <- NULL, index_scaled <- 0
     79 *
     80 * @param[in] xl        Width (in SCI coordinates) of the pixmap
     81 * @param[in] yl        Height (in SCI coordinates) of the pixmap
     82 * @param[in] resid     The pixmap's resource ID, or GFX_RESID_NONE
     83 * @param[in] loop      For views: The pixmap's loop number
     84 * @param[in] cel       For cels: The pixmap's cel number
     85 * @return                      The newly allocated pixmap
     86 */
    7087gfx_pixmap_t *gfx_new_pixmap(int xl, int yl, int resid, int loop, int cel);
    71 /* Creates a new pixmap structure
    72 ** Parameters: (int x int) xl x yl: The dimensions (in SCI coordinates) of the pixmap
    73 **             (int) resid: The pixmap's resource ID, or GFX_RESID_NONE
    74 **             (int) loop: For views: The pixmap's loop number
    75 **             (int) cel: For cels: The pixmap's cel number
    76 ** Returns   : (gfx_pixmap_t *) The newly allocated pixmap
    77 ** The following fiels are initialized:
    78 ** ID, loop, cel, index_width, index_height, xl, yl, data <- NULL,
    79 ** alpha_map <- NULL, internal.handle <- 0, internal.info <- NULL, colors <- NULL,
    80 ** index_scaled <- 0
    81 */
    8288
     89/**
     90 * @brief Clones a pixmap, minus its index data, palette and driver-specific
     91 * handles
     92 *
     93 * @param[in] pixmap    The pixmap to clone
     94 * @param[in] mode              The mode to be applied to the pixmap
     95 * @return                              The clone
     96 */
    8397gfx_pixmap_t *gfx_clone_pixmap(gfx_pixmap_t *pixmap, gfx_mode_t *mode);
    84 /* Clones a pixmap, minus its index data, palette and driver-specific handles
    85 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to clone
    86 **             (gfx_mode_t *) mode: The mode to be applied to the pixmap
    87 ** Returns   : (gfx_pixmap_t *) The clone
    88 */
    89 
    9098
     99/**
     100 * @brief Allocates the index_data field of a pixmap
     101 *
     102 * @param[in] pixmap    The pixmap to allocate for
     103 * @return                              The pixmap
     104 */
    91105gfx_pixmap_t *gfx_pixmap_alloc_index_data(gfx_pixmap_t *pixmap);
    92 /* Allocates the index_data field of a pixmap
    93 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to allocate for
    94 ** Returns   : (gfx_pixmap_t *) pixmap
    95 */
    96106
     107/**
     108 * @brief Frees the index_data field of a pixmap
     109 *
     110 * @param[in] pixmap    The pixmap to modify
     111 * @return                              The pixmap
     112 */
    97113gfx_pixmap_t *gfx_pixmap_free_index_data(gfx_pixmap_t *pixmap);
    98 /* Frees the index_data field of a pixmap
    99 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to modify
    100 ** Returns   : (gfx_pixmap_t *) pixmap
    101 */
    102114
     115/**
     116 * @brief Allocates the data field of a pixmap
     117 *
     118 * @param[in] pixmap    The pixmap to allocate for
     119 * @param[in] mode              The mode the memory is to be allocated for
     120 * @return                              The pixmap
     121 */
    103122gfx_pixmap_t *gfx_pixmap_alloc_data(gfx_pixmap_t *pixmap, gfx_mode_t *mode);
    104 /* Allocates the data field of a pixmap
    105 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to allocate for
    106 **             (gfx_mode_t *) mode: The mode the memory is to be allocated for
    107 ** Returns   : (gfx_pixmap_t *) pixmap
    108 */
    109123
     124/**
     125 * @brief Frees the memory allocated for a pixmap's data field
     126 *
     127 * @param[in] pixmap    The pixmap to modify
     128 * @return                              The pixmap
     129 */
    110130gfx_pixmap_t *gfx_pixmap_free_data(gfx_pixmap_t *pixmap);
    111 /* Frees the memory allocated for a pixmap's data field
    112 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap to modify
    113 ** Returns   : (gfx_pixmap_t *) pixmap
    114 */
    115131
     132/**
     133 * @brief Frees all memory associated with a pixmap
     134 *
     135 * @param[in] pxm       The pixmap to free
     136 */
    116137void gfx_free_pixmap(gfx_pixmap_t *pxm);
    117 /* Frees all memory associated with a pixmap
    118 ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to free
    119 ** Returns   : (void)
    120 */
    121 
    122 void gfx_draw_line_pixmap_i(gfx_pixmap_t *pxm, Common::Point start, Common::Point end, int color);
    123 /* Draws a line to a pixmap's index data buffer
    124 ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to draw to
    125 **             (Common::Point) start: Starting point of the line to draw
    126 **             (Common::Point) end: End point of the line to draw
    127 **             (int) color: The byte value to write
    128 ** Returns   : (void)
    129 ** Remember, this only draws to the /index/ buffer, not to the drawable buffer.
    130 ** The line is not clipped. Invalid x, y, x1, y1 values will result in memory corruption.
    131 */
    132138
     139/**
     140 * @brief Draws a line to a pixmap's index data buffer
     141 *
     142 * Remember, this only draws to the /index/ buffer, not to the drawable buffer.
     143 * The line is not clipped. Invalid x, y, x1, y1 values will result in memory
     144 * corruption.
     145 *
     146 * @param[in] pxm               The pixmap to draw to
     147 * @param[in] start             Starting point of the line to draw
     148 * @param[in] end               End point of the line to draw
     149 * @param[in] color             The byte value to write
     150 */
     151void gfx_draw_line_pixmap_i(gfx_pixmap_t *pxm, Common::Point start,
     152        Common::Point end, int color);
     153
     154/**
     155 * @brief Draws a filled rectangular area to a pixmap's index buffer
     156 *
     157 * This function only draws to the index buffer.
     158 *
     159 * @param[in] pxm       The pixmap to draw to
     160 * @param[in] box       The box to fill
     161 * @param[in] color     The color to use for drawing
     162 */
    133163void gfx_draw_box_pixmap_i(gfx_pixmap_t *pxm, rect_t box, int color);
    134 /* Draws a filled rectangular area to a pixmap's index buffer
    135 ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to draw to
    136 **             (rect_t) box: The box to fill
    137 **             (int) color: The color to use for drawing
    138 ** Returns   : (void)
    139 ** This function only draws to the index buffer.
    140 */
    141164
     165/**
     166 * @brief Copies part of a pixmap to another pixmap, with clipping
     167 *
     168 * @param[in] dest      The destination pixmap
     169 * @param[in] src       The source pixmap
     170 * @param[in] box       The area to copy
     171 */
    142172void gfx_copy_pixmap_box_i(gfx_pixmap_t *dest, gfx_pixmap_t *src, rect_t box);
    143 /* Copies part of a pixmap to another pixmap, with clipping
    144 ** Parameters: (gfx_pixmap_t *) dest: The destination pixmap
    145 **             (gfx_pixmap_t *) src: The source pixmap
    146 **             (rect_t) box: The area to copy
    147 ** Returns   : (void)
    148 */
    149173
     174/**
     175 * @brief Translates a pixmap's index data to drawable graphics data
     176 *
     177 * @param[in] pxm               The pixmap to translate
     178 * @param[in] mode              The mode according which to scale
     179 * @param[in] filter    How to filter the data
     180 */
    150181void gfx_xlate_pixmap(gfx_pixmap_t *pxm, gfx_mode_t *mode, gfx_xlate_filter_t filter);
    151 /* Translates a pixmap's index data to drawable graphics data
    152 ** Parameters: (gfx_pixmap_t *) pxm: The pixmap to translate
    153 **             (gfx_mode_t *) mode: The mode according which to scale
    154 **             (gfx_xlate_filter_t) filter: How to filter the data
    155 ** Returns   : (void)
    156 */
    157182
    158 #define GFX_CROSSBLIT_FLAG_DATA_IS_HOMED (1<<0)
    159 /* Means that the first byte in the visual data refers to the
    160 ** point corresponding to (dest.x, dest.y) */
     183#define GFX_CROSSBLIT_FLAG_DATA_IS_HOMED (1<<0) /**< Means that the first byte in the visual data refers to the point corresponding to (dest.x, dest.y) */
    161184
     185/**
     186 * @brief Transfers the non-transparent part of a pixmap to a linear pixel
     187 * buffer.
     188 *
     189 * A 'linear buffer' in this context means a data buffer containing an entire
     190 * screen (visual or priority), with fixed offsets between each data row, and
     191 * linear access.
     192 *
     193 * @param[in] mode                                      The graphics mode of the target buffer
     194 * @param[in] pxm                                       The pixmap to transfer
     195 * @param[in] priority                          The pixmap's priority
     196 * @param[in] src_coords                        The source coordinates within the pixmap
     197 * @param[in] dest_coords                       The destination coordinates (no scaling)
     198 * @param[in] dest                                      Memory position of the upper left pixel of
     199 *                                                                      the linear pixel buffer
     200 * @param[in] dest_line_width           Byte offset of the very first pixel in the
     201 *                                                                      second line of the linear pixel buffer,
     202 *                                                                      relative to dest.
     203 * @param[in] priority_dest                     Destination buffer for the pixmap's priority
     204 *                                                                      values
     205 * @param[in] priority_line_width       Byte offset of the first pixel in the second
     206 *                                                                      line of the priority buffer
     207 * @param[in] priority_skip                     Amount of bytes allocated by each priority
     208 *                                                                      value
     209 * @param[in] flags                                     Any crossblit flags
     210 * @return                                                      GFX_OK, or GFX_ERROR if the specified mode
     211 *                                                                      was invalid or unsupported
     212 */
    162213int gfx_crossblit_pixmap(gfx_mode_t *mode, gfx_pixmap_t *pxm, int priority,
    163214        rect_t src_coords, rect_t dest_coords, byte *dest, int dest_line_width,
    164215        byte *priority_dest, int priority_line_width, int priority_skip, int flags);
    165 /* Transfers the non-transparent part of a pixmap to a linear pixel buffer
    166 ** Parameters: (gfx_mode_t *) mode: The graphics mode of the target buffer
    167 **             (gfx_pixmap_t *) pxm: The pixmap to transfer
    168 **             (int priority): The pixmap's priority
    169 **             (rect_t) src_coords: The source coordinates within the pixmap
    170 **             (rect_t) dest_coords: The destination coordinates (no scaling)
    171 **             (byte *) dest: Memory position of the upper left pixel of the
    172 **                      linear pixel buffer
    173 **             (int) dest_line_width: Byte offset of the very first pixel in the
    174 **                                    second line of the linear pixel buffer,
    175 **                                    relative to dest.
    176 **             (byte *) priority_dest: Destination buffer for the pixmap's priority
    177 **                                     values
    178 **             (int) priority_line_width: Byte offset of the first pixel in the
    179 **                                        second line of the priority buffer
    180 **             (int) priority_skip: Amount of bytes allocated by each priority value
    181 **             (int) flags: Any crossblit flags
    182 ** Returns   : (int) GFX_OK, or GFX_ERROR if the specified mode was invalid or unsupported
    183 ** A 'linear buffer' in this context means a data buffer containing an entire
    184 ** screen (visual or priority), with fixed offsets between each data row, and
    185 ** linear access.
    186 */
    187216
     217
     218/**
     219 * @brief Scales the index data associated with a pixmap
     220 *
     221 * @param[in] pixmap    The pixmap whose index data should be scaled
     222 * @param[in] mode              The mode to scale it to
     223 * @return                              The pixmap
     224 */
    188225gfx_pixmap_t *gfx_pixmap_scale_index_data(gfx_pixmap_t *pixmap, gfx_mode_t *mode);
    189 /* Scales the index data associated with a pixmap
    190 ** Parameters: (gfx_pixmap_t *) pixmap: The pixmap whose index data should be scaled
    191 **             (gfx_mode_t *) mode: The mode to scale it to
    192 ** Returns   : (gfx_pixmap_t *) pixmap
    193 */
    194226
     227/** @} */
    195228} // End of namespace Sci
    196229
    197230#endif // SCI_GFX_GFX_TOOLS_H
  • engines/sci/gfx/gfx_widgets.h

    diff --git a/engines/sci/gfx/gfx_widgets.h b/engines/sci/gfx/gfx_widgets.h
    index bd884ff..4c12328 100644
    a b  
    2323 *
    2424 */
    2525
    26 /* Graphical state management */
    2726
    2827#ifndef SCI_GFX_GFX_WIDGETS_H
    2928#define SCI_GFX_GFX_WIDGETS_H
     
    3433#include "sci/gfx/operations.h"
    3534
    3635namespace Sci {
     36/** @name Widget Graphical State Management */
     37/** @{ */
    3738
    3839struct GfxState;
    3940struct GfxBox;
    extern Common::Point gfxw_point_zero;  
    155156
    156157/*-- Primitive types --*/
    157158
     159/**
     160 * @brief Creates a new box
     161 *
     162 * The graphics state, if non-NULL, is used here for some optimizations.
     163 *
     164 * @param[in] state                     The (optional) state
     165 * @param[in] area                      The box's dimensions, relative to its container
     166 *                                                      widget
     167 * @param[in] color1            The primary color
     168 * @param[in] color2            The secondary color (ignored if shading is disabled)
     169 * @param[in] shade_type        The shade type for the box
     170 * @return                                      The resulting box widget
     171 */
    158172GfxBox *gfxw_new_box(GfxState *state, rect_t area, gfx_color_t color1, gfx_color_t color2, gfx_box_shade_t shade_type);
    159 /* Creates a new box
    160 ** Parameters: (GfxState *) state: The (optional) state
    161 **             (rect_t) area: The box's dimensions, relative to its container widget
    162 **             (gfx_color_t) color1: The primary color
    163 **             (gfx_color_t) color1: The secondary color (ignored if shading is disabled)
    164 **             (gfx_box_shade_t) shade_type: The shade type for the box
    165 ** Returns   : (GfxBox *) The resulting box widget
    166 ** The graphics state- if non-NULL- is used here for some optimizations.
    167 */
    168173
    169 GfxPrimitive *gfxw_new_rect(rect_t rect, gfx_color_t color, gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    170 /* Creates a new rectangle
    171 ** Parameters: (rect_t) rect: The rectangle area
    172 **             (gfx_color_t) color: The rectangle's color
    173 **             (gfx_line_mode_t) line_mode: The line mode for the lines that make up the rectangle
    174 **             (gfx_line_style_t) line_style: The rectangle's lines' style
    175 ** Returns   : (GfxPrimitive *) The newly allocated rectangle widget (a Primitive)
    176 */
     174/**
     175 * @brief Creates a new rectangle
     176 *
     177 * @param[in] rect                      The rectangle area
     178 * @param[in] color                     The rectangle's color
     179 * @param[in] line_mode         The line mode for the lines that make up the
     180 *                                                      rectangle
     181 * @param[in] line_style        The rectangle's lines' style
     182 * @return                                      The newly allocated rectangle widget (a Primitive)
     183 */
     184GfxPrimitive *gfxw_new_rect(rect_t rect, gfx_color_t color,
     185        gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    177186
    178 GfxPrimitive *gfxw_new_line(Common::Point start, Common::Point end, gfx_color_t color, gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    179 /* Creates a new line
    180 ** Parameters: (Common::Point * Common::Point) (start, line): The line origin and end point
    181 **             (gfx_color_t) color: The line's color
    182 **             (gfx_line_mode_t) line_mode: The line mode to use for drawing
    183 **             (gfx_line_style_t) line_style: The line style
    184 ** Returns   : (GfxPrimitive *) The newly allocated line widget (a Primitive)
    185 */
     187/**
     188 * @brief Creates a new line
     189 *
     190 * @param[in] start                     The line's origin
     191 * @param[in] end                       The line's end point
     192 * @param[in] color                     The line's color
     193 * @param[in] line_mode         The line mode to use for drawing
     194 * @param[in] line_style        The line style
     195 * @return                                      The newly allocated line widget (a Primitive)
     196 */
     197GfxPrimitive *gfxw_new_line(Common::Point start, Common::Point end,
     198        gfx_color_t color, gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    186199
     200/** @brief View flags */
     201enum {
     202        GFXW_VIEW_FLAG_STATIC = (1 << 0), /**< Whether the view should be static */
     203        GFXW_VIEW_FLAG_DONT_MODIFY_OFFSET = (1 << 1) /**< Whether the view should _not_ apply its x/y offset modifyers */
     204};
    187205
    188 /* Whether the view should be static */
    189 #define GFXW_VIEW_FLAG_STATIC (1 << 0)
    190 
    191 /* Whether the view should _not_ apply its x/y offset modifyers */
    192 #define GFXW_VIEW_FLAG_DONT_MODIFY_OFFSET (1 << 1)
    193 
    194 GfxView *gfxw_new_view(GfxState *state, Common::Point pos, int view, int loop, int cel, int palette, int priority, int control,
    195         gfx_alignment_t halign, gfx_alignment_t valign, int flags);
    196 /* Creates a new view (a cel, actually)
    197 ** Parameters: (GfxState *) state: The graphics state
    198 **             (Common::Point) pos: The position to place the view at
    199 **             (int x int x int) view, loop, cel: The global cel ID
    200 **             (int) priority: The priority to use for drawing, or -1 for none
    201 **             (int) control: The value to write to the control map, or -1 for none
    202 **             (gfx_alignment_t x gfx_alignment_t) halign, valign: Horizontal and vertical
    203 **                                                                 cel alignment
    204 **             (int) flags: Any combination of GFXW_VIEW_FLAGs
    205 ** Returns   : (gfxw_cel_t *) A newly allocated cel according to the specs
    206 */
     206/**
     207 * @brief Creates a new view (a cel, actually)
     208 *
     209 * @param[in] state             The graphics state
     210 * @param[in] pos               The position to place the view at
     211 * @param[in] view              The global cel ID
     212 * @param[in] loop              The global cel ID
     213 * @param[in] cel               The global cel ID
     214 * @param[in] palette   The palette to use
     215 * @param[in] priority  The priority to use for drawing, or -1 for none
     216 * @param[in] control   The value to write to the control map, or -1 for none
     217 * @param[in] halign    Horizontal cel alignment
     218 * @param[in] valign    Vertical cel alignment
     219 * @param[in] flags             Any combination of GFXW_VIEW_FLAGs
     220 * @return                              A newly allocated cel according to the specs
     221 */
     222GfxView *gfxw_new_view(GfxState *state, Common::Point pos, int view, int loop,
     223        int cel, int palette, int priority, int control, gfx_alignment_t halign,
     224        gfx_alignment_t valign, int flags);
    207225
    208 GfxDynView *gfxw_new_dyn_view(GfxState *state, Common::Point pos, int z, int view, int loop, int cel, int palette,
    209         int priority, int control, gfx_alignment_t halign, gfx_alignment_t valign, int sequence);
    210 /* Creates a new dyn view
    211 ** Parameters: (GfxState *) state: The graphics state
    212 **             (Common::Point) pos: The position to place the dynamic view at
    213 **             (int) z: The z coordinate
    214 **             (int x int x int) view, loop, cel: The global cel ID
    215 **             (int) priority: The priority to use for drawing, or -1 for none
    216 **             (int) control: The value to write to the control map, or -1 for none
    217 **             (gfx_alignment_t x gfx_alignment_t) halign, valign: Horizontal and vertical
    218 **                                                                 cel alignment
    219 **             (int) sequence: Sequence number: When sorting dynviews, this number is
    220 **                             considered last for sorting (ascending order)
    221 ** Returns   : (gfxw_cel_t *) A newly allocated cel according to the specs
    222 ** Dynamic views are non-pic views with a unique global identifyer. This allows for drawing
    223 ** optimizations when they move or change shape.
    224 */
    225226
    226 GfxText *gfxw_new_text(GfxState *state, rect_t area, int font, const char *text, gfx_alignment_t halign,
    227         gfx_alignment_t valign, gfx_color_t color1, gfx_color_t color2,
    228         gfx_color_t bgcolor, int flags);
    229 /* Creates a new text widget
    230 ** Parameters: (GfxState *) state: The state the text is to be calculated from
    231 **             (rect_t) area: The area the text is to be confined to (the yl value is only
    232 **                            relevant for text aligment, though)
    233 **             (int) font: The number of the font to use
    234 **             (gfx_alignment_t x gfx_alignment_t) halign, valign: Horizontal and
    235 **                                                                 vertical text alignment
    236 **             (gfx_color_t x gfx_color_t) color1, color2: Text foreground colors (if not equal,
    237 **                                                         The foreground is dithered between them)
    238 **             (gfx_color_t) bgcolor: Text background color
    239 **             (int) flags: GFXR_FONT_FLAGs, orred together (see gfx_resource.h)
    240 ** Returns   : (GfxText *) The resulting text widget
    241 */
     227/**
     228 * @brief Creates a new dyn view
     229 *
     230 * Dynamic views are non-pic views with a unique global identifyer. This allows for drawing optimizations when they move or change shape.
     231 *
     232 * @param[in] state             The graphics state
     233 * @param[in] pos               The position to place the dynamic view at
     234 * @param[in] z                 The z coordinate
     235 * @param[in] view              The global cel ID
     236 * @param[in] loop              The global cel ID
     237 * @param[in] cel               The global cel ID
     238 * @param[in] palette   The palette to use
     239 * @param[in] priority  The priority to use for drawing, or -1 for none
     240 * @param[in] control   The value to write to the control map, or -1 for none
     241 * @param[in] halign    Horizontal cel alignment
     242 * @param[in] valign    Vertical cel alignment
     243 * @param[in] sequence  Sequence number: When sorting dynviews, this number is
     244 *                                              considered last for sorting (ascending order)
     245 * @return                              A newly allocated cel according to the specs
     246 */
     247GfxDynView *gfxw_new_dyn_view(GfxState *state, Common::Point pos, int z,
     248        int view, int loop, int cel, int palette, int priority, int control,
     249        gfx_alignment_t halign, gfx_alignment_t valign, int sequence);
    242250
     251/**
     252 * @brief Creates a new text widget
     253 *
     254 * @param[in] state             The state the text is to be calculated from
     255 * @param[in] area              The area the text is to be confined to (the yl value is
     256 *                                              only relevant for text aligment, though)
     257 * @param[in] font              The number of the font to use
     258 * @param[in] text              String to put in text widget
     259 * @param[in] halign    Horizontal text alignment
     260 * @param[in] valign    Vertical text alignment
     261 * @param[in] color1    Text foreground colors (if not equal, the foreground is
     262 *                                              dithered between them)
     263 * @param[in] color2    Text foreground colors (if not equal, the foreground is
     264 *                                              dithered between them)
     265 * @param[in] bgcolor   Text background color
     266 * @param[in] flags             GFXR_FONT_FLAGs, orred together (see gfx_resource.h)
     267 * @return                              The resulting text widget
     268 */
     269GfxText *gfxw_new_text(GfxState *state, rect_t area, int font, const char *text,
     270        gfx_alignment_t halign, gfx_alignment_t valign, gfx_color_t color1,
     271        gfx_color_t color2,     gfx_color_t bgcolor, int flags);
     272
     273/**
     274 * @brief Determines text widget meta-information
     275 *
     276 * @param[in]  state            The state to operate on
     277 * @param[in]  text                     The widget to query
     278 * @param[out] lines_nr         Number of lines used in the text
     279 * @param[out] lineheight       Pixel height (SCI scale) of each text line
     280 * @param[out] offset           Pixel offset (SCI scale) of the space after the last
     281 *                                                      character in the last line
     282 */
    243283void gfxw_text_info(GfxState *state, GfxText *text, int *lines_nr,
    244284        int *lineheight, int *offset);
    245 /* Determines text widget meta-information
    246 ** Parameters: (GfxState *) state: The state to operate on
    247 **             (gfx_text_t *) text: The widget to query
    248 ** Returns   : (int) lines_nr: Number of lines used in the text
    249 **             (int) lineheight: Pixel height (SCI scale) of each text line
    250 **             (int) offset: Pixel offset (SCI scale) of the space after the
    251 **                           last character in the last line
    252 */
    253285
     286/**
     287 * @brief Sets a widget's ID
     288 *
     289 * A widget ID is unique within the container it is stored in, if and only if it
     290 * was added to that container with gfxw_add(). This function handles widget ==
     291 * NULL gracefully (by doing nothing and returning NULL).
     292 *
     293 * @param[in] widget    The widget whose ID should be set
     294 * @param[in] ID                The ID to set
     295 * @param[in] subID             The ID to set
     296 * @return                              The widget
     297 */
    254298GfxWidget *gfxw_set_id(GfxWidget *widget, int ID, int subID);
    255 /* Sets a widget's ID
    256 ** Parmaeters: (GfxWidget *) widget: The widget whose ID should be set
    257 **             (int x int) ID, subID: The ID to set
    258 ** Returns   : (GfxWidget *) widget
    259 ** A widget ID is unique within the container it is stored in, if and only if it was
    260 ** added to that container with gfxw_add().
    261 ** This function handles widget = NULL gracefully (by doing nothing and returning NULL).
    262 */
    263299
     300/**
     301 * @brief Finds a widget with a specific ID in a container and removes it from there
     302 *
     303 * Search is non-recursive; widgets with IDs hidden in subcontainers will not
     304 * be found.
     305 *
     306 * @param[in] container The container to search in
     307 * @param[in] ID                The ID to look for
     308 * @param[in] subID             The subID to look for, or GFXW_NO_ID for any
     309 * @return                              The resulting widget or NULL if no match was found
     310 */
    264311GfxWidget *gfxw_remove_id(GfxContainer *container, int ID, int subID);
    265 /* Finds a widget with a specific ID in a container and removes it from there
    266 ** Parameters: (GfxContainer *) container: The container to search in
    267 **             (int) ID: The ID to look for
    268 **             (int) subID: The subID to look for, or GFXW_NO_ID for any
    269 ** Returns   : (GfxWidget *) The resulting widget or NULL if no match was found
    270 ** Search is non-recursive; widgets with IDs hidden in subcontainers will not be found.
    271 */
    272312
     313/**
     314 * @brief Initializes a dyn view's interpreter attributes
     315 *
     316 * @param[in] widget            The widget affected
     317 * @param[in] under_bits        Interpreter-dependant data
     318 * @param[in] under_bitsp       Interpreter-dependant data
     319 * @param[in] signal            Interpreter-dependant data
     320 * @param[in] signalp           Interpreter-dependant data
     321 * @return                                      The widget
     322 */
     323GfxDynView *gfxw_dyn_view_set_params(GfxDynView *widget, int under_bits,
     324        const ObjVarRef& under_bitsp, int signal, const ObjVarRef& signalp);
    273325
    274 GfxDynView *gfxw_dyn_view_set_params(GfxDynView *widget, int under_bits, const ObjVarRef& under_bitsp, int signal, const ObjVarRef& signalp);
    275 /* Initializes a dyn view's interpreter attributes
    276 ** Parameters: (GfxDynView *) widget: The widget affected
    277 **             (int x void * x int x void *) under_bits, inder_bitsp, signal, signalp: Interpreter-dependant data
    278 ** Returns   : (GfxDynView *) widget
    279 */
    280 
     326/**
     327 * @brief Makes a widget invisible without removing it from the list of widgets
     328 *
     329 * Has no effect on invisible widgets
     330 *
     331 * @param[in] widget    The widget to invisibilize
     332 * @return                              The widget
     333 */
    281334GfxWidget *gfxw_hide_widget(GfxWidget *widget);
    282 /* Makes a widget invisible without removing it from the list of widgets
    283 ** Parameters: (GfxWidget *) widget: The widget to invisibilize
    284 ** Returns   : (GfxWidget *) widget
    285 ** Has no effect on invisible widgets
    286 */
    287335
     336/**
     337 * @brief Makes an invisible widget reappear
     338 *
     339 * Does not affect visible widgets
     340 *
     341 * @param[in] widget    The widget to show again
     342 * @return                              The widget
     343 */
    288344GfxWidget *gfxw_show_widget(GfxWidget *widget);
    289 /* Makes an invisible widget reappear
    290 ** Parameters: (GfxWidget *) widget: The widget to show again
    291 ** Returns   : (GfxWidget *) widget
    292 ** Does not affect visible widgets
    293 */
    294345
     346/**
     347 * @brief Marks a widget as "abandoned"
     348 *
     349 * @param[in] widget    The widget to abandon
     350 * @return                              The widget
     351 */
    295352GfxWidget *gfxw_abandon_widget(GfxWidget *widget);
    296 /* Marks a widget as "abandoned"
    297 ** Parameters: (GfxWidget *) widget: The widget to abandon
    298 ** Returns   : (GfxWidget *) widget
    299 */
    300 
    301 /*-- Container types --*/
    302353
    303 #define GFXW_LIST_UNSORTED 0
    304 #define GFXW_LIST_SORTED 1
     354/** @brief Container types */
     355enum {
     356        GFXW_LIST_UNSORTED = 0,
     357        GFXW_LIST_SORTED = 1
     358};
    305359
     360/**
     361 * @brief Creates a new list widget
     362 *
     363 * List widgets are also referred to as Display Lists.
     364 *
     365 * @param[in] area              The area covered by the list (absolute position)
     366 * @param[in] sorted    Whether the list should be a sorted list
     367 * @return                              A newly allocated list widget
     368 */
    306369GfxList *gfxw_new_list(rect_t area, int sorted);
    307 /* Creates a new list widget
    308 ** Parameters: (rect_t) area: The area covered by the list (absolute position)
    309 **             (int) sorted: Whether the list should be a sorted list
    310 ** Returns   : (GfxList *) A newly allocated list widget
    311 ** List widgets are also referred to as Display Lists.
    312 */
    313370
     371/**
     372 * @brief Retrieves the default port from a visual
     373 *
     374 * The 'default port' is the last port to be instantiated; usually the topmost
     375 * or highest-ranking port.
     376 *
     377 * @param[in] visual    The visual the port should be retrieved from
     378 * @return                              The default port, or NULL if no port is present
     379 */
    314380GfxPort *gfxw_find_default_port(GfxVisual *visual);
    315 /* Retrieves the default port from a visual
    316 ** Parameters: (GfxVisual *) visual: The visual the port should be retrieved from
    317 ** Returns   : (GfxPort *) The default port, or NULL if no port is present
    318 ** The 'default port' is the last port to be instantiated; usually the topmost
    319 ** or highest-ranking port.
    320 */
    321381
     382/**
     383 * @brief Sets rectangle to be restored upon port removal
     384 *
     385 * @param[in] visual    The visual to operate on
     386 * @param[in] window    The affected window
     387 * @param[in] auto_rect The area to restore
     388 */
    322389void gfxw_port_set_auto_restore(GfxVisual *visual, GfxPort *window, rect_t auto_rect);
    323 /* Sets rectangle to be restored upon port removal
    324 ** Parameters: (state_t *) s: The state to operate on
    325 **             (GfxPort *) window: The affected window
    326 **             (rect_t) auto_rect: The area to restore
    327 ** Returns   : (void)
    328 */
    329390
     391/**
     392 * @brief Removes a port from a visual
     393 *
     394 * @param[in] visual    The visual the port should be removed from
     395 * @param[in] port              The port to remove
     396 * @return                              port's parent port, or NULL if it had none
     397 */
    330398GfxPort *gfxw_remove_port(GfxVisual *visual, GfxPort *port);
    331 /* Removes a port from a visual
    332 ** Parameters: (GfxVisual *) visual: The visual the port should be removed from
    333 **             (GfxPort *) port: The port to remove
    334 ** Returns   : (GfxPort *) port's parent port, or NULL if it had none
    335 */
    336399
     400/**
     401 * Removes the widget from the specified port
     402 *
     403 * @param[in] container The container it should be removed from
     404 * @param[in] widget    The widget to remove
     405 */
    337406void gfxw_remove_widget_from_container(GfxContainer *container, GfxWidget *widget);
    338 /* Removes the widget from the specified port
    339 ** Parameters: (GfxContainer *) container: The container it should be removed from
    340 **             (GfxWidget *) widget: The widget to remove
    341 ** Returns   : (void)
    342 */
    343407
     408/**
     409 * @brief Makes a "snapshot" of a visual
     410 *
     411 * It's not really a full qualified snaphot, though. See gfxw_restore_snapshot
     412 * for a full discussion. This operation also increases the global serial number
     413 * counter by one.
     414 *
     415 * @param[in] visual    The visual a snapshot is to be taken of
     416 * @param[in] area              The area a snapshot should be taken of
     417 * @return                              The resulting, newly allocated snapshot
     418 */
    344419gfxw_snapshot_t *gfxw_make_snapshot(GfxVisual *visual, rect_t area);
    345 /* Makes a "snapshot" of a visual
    346 ** Parameters: (GfxVisual *) visual: The visual a snapshot is to be taken of
    347 **             (rect_t) area: The area a snapshot should be taken of
    348 ** Returns   : (gfxw_snapshot_t *) The resulting, newly allocated snapshot
    349 ** It's not really a full qualified snaphot, though. See gfxw_restore_snapshot
    350 ** for a full discussion.
    351 ** This operation also increases the global serial number counter by one.
    352 */
    353420
     421/**
     422 * @brief Predicate to test whether a widget would be destroyed by applying a snapshot
     423 *
     424 * @param[in] snapshot  The snapshot to test against
     425 * @param[in] widget    The widget to test
     426 * @return                              An appropriate boolean value
     427 */
    354428int gfxw_widget_matches_snapshot(gfxw_snapshot_t *snapshot, GfxWidget *widget);
    355 /* Predicate to test whether a widget would be destroyed by applying a snapshot
    356 ** Parameters: (gfxw_snapshot_t *) snapshot: The snapshot to test against
    357 **             (GfxWidget *) widget: The widget to test
    358 ** Retunrrs  : (int) An appropriate boolean value
    359 */
    360429
     430/**
     431 * @brief Restores a snapshot to a visual
     432 *
     433 * The snapshot is not really restored; only more recent widgets touching
     434 * the snapshotted area are destroyed.
     435 *
     436 * @param[in] visual    The visual to operate on
     437 * @param[in] snapshot  The snapshot to restore
     438 * @return                              The snapshot (still needs to be freed)
     439 */
    361440gfxw_snapshot_t *gfxw_restore_snapshot(GfxVisual *visual, gfxw_snapshot_t *snapshot);
    362 /* Restores a snapshot to a visual
    363 ** Parameters: (GfxVisual *) visual: The visual to operate on
    364 **             (gfxw_snapshot_t *) snapshot: The snapshot to restore
    365 ** Returns   : (gfxw_snapshot_t *) snapshot (still needs to be freed)
    366 ** The snapshot is not really restored; only more recent widgets touching
    367 ** the snapshotted area are destroyed.
    368 */
    369441
     442/**
     443 * @brief As widget->widfree(widget), but destroys all overlapping widgets
     444 *
     445 * This operation calls widget->widfree(widget), but it also destroys all
     446 * widgets with a higher or equal priority drawn after this widget.
     447 *
     448 * @param[in] widget    The widget to use
     449 */
    370450void gfxw_annihilate(GfxWidget *widget);
    371 /* As widget->widfree(widget), but destroys all overlapping widgets
    372 ** Parameters: (GfxWidget *) widget: The widget to use
    373 ** Returns   : (void)
    374 ** This operation calls widget->widfree(widget), but it also destroys
    375 ** all widgets with a higher or equal priority drawn after this widget.
    376 */
    377451
     452/**
     453 * @brief Turns a dynview into a picview
     454 *
     455 * The only changes are in function and type variables, actually.
     456 *
     457 * @param[in] dynview   The victim
     458 * @return                              The victim, after his transformation
     459 */
    378460GfxDynView *gfxw_picviewize_dynview(GfxDynView *dynview);
    379 /* Turns a dynview into a picview
    380 ** Parameters: (GfxDynView *) dynview: The victim
    381 ** Returns   : (GfxDynView *) The victim, after his transformation
    382 ** The only changes are in function and type variables, actually.
    383 */
    384461
    385 void gfxw_port_auto_restore_background(GfxVisual *visual, GfxPort *window, rect_t auto_rect);
    386 /* Tags a window widget as automatically restoring the visual background upon removal
    387 ** Parameters: (gfx_visual_t *) visual: The base visual
    388 **             (GfxPort *) window: The window to tag
    389 **             (rect_t) auto_rect: The background to remember
    390 ** Also records the specified background rectangle, for later recovery
    391 */
     462/**
     463 * @brief Tags a window widget as automatically restoring the visual background
     464 * upon removal.
     465 *
     466 * Also records the specified background rectangle, for later recovery.
     467 *
     468 * @param[in] visual    The base visual
     469 * @param[in] window    The window to tag
     470 * @param[in] auto_rect The background to remember
     471
     472 */
     473void gfxw_port_auto_restore_background(GfxVisual *visual, GfxPort *window,
     474        rect_t auto_rect);
    392475
     476/** @} */
    393477} // End of namespace Sci
    394478
    395479#endif // SCI_GFX_GFX_WIDGETS_H
  • engines/sci/gfx/menubar.h

    diff --git a/engines/sci/gfx/menubar.h b/engines/sci/gfx/menubar.h
    index 02d9933..b775dd8 100644
    a b struct EngineState;  
    5050/* The number of pixels added to the left of the first menu */
    5151
    5252#define MENU_BOX_CENTER_PADDING 10
    53 /* Number of pixels to leave in between the left and the right centered text content in boxes
    54 ** that use right centered content
    55 */
     53/* Number of pixels to leave in between the left and the right centered text content in boxes that use right centered content */
    5654
    5755#define MENU_BOX_LEFT_PADDING 0
    5856/* Number of pixels to pad to the left */
    enum MenuType {  
    8886
    8987class MenuItem : public Common::Serializable {
    9088public:
    91         MenuType _type; /* Normal or hbar */
    92         Common::String _keytext; /* right-centered part of the text (the key) */
     89        MenuType _type; /**< Normal or hbar */
     90        Common::String _keytext; /**< right-centered part of the text (the key) */
    9391
    9492        int _flags;
    95         byte _said[MENU_SAID_SPEC_SIZE]; /* Said spec for this item */
     93        byte _said[MENU_SAID_SPEC_SIZE]; /**< Said spec for this item */
    9694        reg_t _saidPos;
    9795        Common::String _text;
    9896        reg_t _textPos;
    99         int _modifiers; /* Hotkey for this item */
    100         int _key; /* Hotkey for this item */
     97        int _modifiers; /**< Hotkey for this item */
     98        int _key; /**< Hotkey for this item */
    10199        int _enabled;
    102100        int _tag;
    103101
    public:  
    107105        virtual void saveLoadWithSerializer(Common::Serializer &ser);
    108106
    109107        /**
    110          * Determines whether a message/modifiers key pair matches a menu item's key parameters.
    111          * @param message               The message to match
    112          * @param modifiers             The modifier flags to match
    113          * @return true on match, false otherwise
     108         * @brief Determines whether a message/modifiers key pair matches a menu item's key parameters.
     109         *
     110         * @param[in] message           The message to match
     111         * @param[in] modifiers         The modifier flags to match
     112         * @return                                      true on match, false otherwise
    114113         */
    115114        bool matchKey(int message, int modifiers);
    116115};
    public:  
    155154        virtual void saveLoadWithSerializer(Common::Serializer &ser);
    156155
    157156        /**
    158          * Adds a menu to the menubar.
    159          * Parameters: (GfxState *) state: The state the fonts are stored in
    160          *             (char *) title: The menu title
    161          *             (char *) entries: A string of menu entries
    162          *             (int) font: The font which is to be used for drawing
    163          *             (reg_t) entries_base: Segmented VM address of the entries string
    164          * Returns   : (void)
     157         * @brief Adds a menu to the menubar.
     158         *
    165159         * The menu entries use the following special characters:
    166160         * '`' : Right justify the following part
    167161         * ':' : End of this entry
    168162         * '#' : Function key (replaced by 'F')
    169163         * '^' : Control key (replaced by \002, which looks like "CTRL")
    170164         * '=' : Initial tag value
    171          * and the special string "--!", which represents a horizontal bar in the menu.
     165         * and the special string "--!", which represents a horizontal bar in the
     166         * menu.
     167         *
     168         * @param[in] state                     The state the fonts are stored in
     169         * @param[in] title                     The menu title
     170         * @param[in] entries           A string of menu entries
     171         * @param[in] font                      The font which is to be used for drawing
     172         * @param[in] entries_base      Segmented VM address of the entries string
    172173         */
    173174        void addMenu(GfxState *state, const char *title, const char *entries, int font, reg_t entries_base);
    174175
    175176
    176177        /**
    177          * Sets the (currently unidentified) foo and bar values.
    178          * Parameters: (state_t *) s: The current state
    179          *             (int) menu: The menu number to edit
    180          *             (int) item: The menu item to change
    181          *             (int) attribute: The attribute to modify
    182          *             (int) value: The value the attribute should be set to
    183          * Returns   : (int) 0 on success, 1 if either menu or item were invalid
     178         * @brief Sets the attributes for a menu item.
     179         *
     180         * @param[in] s                 The current state
     181         * @param[in] menu              The menu number to edit
     182         * @param[in] item              The menu item to change
     183         * @param[in] attribute The attribute to modify
     184         * @param[in] value             The value the attribute should be set to
     185         * @return                              0 on success, 1 if either menu or item were invalid
    184186         */
    185187        int setAttribute(EngineState *s, int menu, int item, int attribute, reg_t value);
    186188
    187189
    188190        /**
    189          * Sets the (currently unidentified) foo and bar values.
    190          * Parameters: (int) menu: The menu number
    191          *             (int) item: The menu item to read
    192          *             (int) attribute: The attribute to read from
    193          * Returns   : (int) The attribute value, or -1 on error
     191         * @brief Gets an attribute for a menuitem.
     192         *
     193         * @param[in] menu              The menu number
     194         * @param[in] item              The menu item to read
     195         * @param[in] attribute The attribute to read from
     196         * @return                              The attribute value, or -1 on error
    194197         */
    195198        reg_t getAttribute(int menu, int item, int attribute) const;
    196199
    197200
    198201        /**
    199          * Determines whether the specified menu entry may be activated.
    200          * @return true if the menu item may be selected, false otherwise
     202         * @brief Determines whether the specified menu entry may be activated.
     203         *
     204         * @return      true if the menu item may be selected, false otherwise
    201205         */
    202206        bool itemValid(int menu, int item) const;
    203207
    204208
    205209        /**
    206          * Maps the pointer position to a (menu,item) tuple.
    207          * @param pointerPos    the current pointer position
    208          * @param menu_nr               the current menu (updated by this function if necessary)
    209          * @param item_nr               the current menu item (updated by this function if necessary)
    210          * @param port                  the port of the currently active menu (if any)
    211          * @return true if the pointer is outside a valid port, false otherwise.
     210         * @brief Maps the pointer position to a (menu,item) tuple.
     211         *
     212         * @param[in] pointerPos        the current pointer position
     213         * @param[in] menu_nr           the current menu (updated by this function if
     214         *                                                      necessary)
     215         * @param[in] item_nr           the current menu item (updated by this function
     216         *                                                      if necessary)
     217         * @param[in] port                      the port of the currently active menu (if any)
     218         * @return                                      true if the pointer is outside a valid port,
     219         *                                                      false otherwise.
    212220         */
    213221        bool mapPointer(const Common::Point &pointerPos, int &menu_nr, int &item_nr, GfxPort *port) const;
    214222
  • engines/sci/gfx/operations.h

    diff --git a/engines/sci/gfx/operations.h b/engines/sci/gfx/operations.h
    index d559d3b..de8e036 100644
    a b typedef Common::List<rect_t> DirtyRectList;  
    9393struct GfxState {
    9494        gfx_options_t *options;
    9595
    96         Common::Point pointer_pos; /* Mouse pointer coordinates */
     96        Common::Point pointer_pos; /**< @brief Mouse pointer coordinates */
    9797
    98         rect_t clip_zone_unscaled; /* The current UNSCALED clipping zone */
    99         rect_t clip_zone; /* The current SCALED clipping zone; a cached scaled version of clip_zone_unscaled */
     98        rect_t clip_zone_unscaled; /**< @brief The current UNSCALED clipping zone */
     99        rect_t clip_zone; /**< @brief The current SCALED clipping zone; a cached scaled version of clip_zone_unscaled */
    100100
    101101        GfxDriver *driver;
    102102
    struct GfxState {  
    104104
    105105        GfxResManager *gfxResMan;
    106106
    107         gfx_pixmap_t *priority_map; /* back buffer priority map (unscaled) */
    108         gfx_pixmap_t *static_priority_map; /* static buffer priority map (unscaled) */
    109         gfx_pixmap_t *control_map; /* back buffer control map (only exists unscaled in the first place) */
     107        gfx_pixmap_t *priority_map; /**< @brief back buffer priority map (unscaled) */
     108        gfx_pixmap_t *static_priority_map; /**< @brief static buffer priority map (unscaled) */
     109        gfx_pixmap_t *control_map; /**< @brief back buffer control map (only exists unscaled in the first place) */
    110110
    111111
    112         int tag_mode; /* Set to 1 after a new pic is drawn and the resource manager
    113                       ** has tagged all resources. Reset after the next front buffer
    114                       ** update is done, when all resources that are still tagged are
    115                       ** flushed.  */
     112        int tag_mode; /**< @brief Set to 1 after a new pic is drawn and the resource manager has tagged all resources. Reset after the next front buffer update is done, when all resources that are still tagged are flushed.  */
    116113
    117         int disable_dirty; /* Set to 1 to disable dirty rect accounting */
     114        int disable_dirty; /**< @brief Set to 1 to disable dirty rect accounting */
    118115
    119         int pic_nr; /* Number of the current pic */
    120         int palette_nr; /* Palette number of the current pic */
     116        int pic_nr; /**< @brief Number of the current pic */
     117        int palette_nr; /**< @brief Palette number of the current pic */
    121118
    122119        Common::List<sci_event_t> _events;
    123120
    124         gfx_pixmap_t *fullscreen_override; /* An optional override picture which must have unscaled
    125                                            ** full-screen size, which overrides all other visibility, and
    126                                            ** which is generally slow */
     121        gfx_pixmap_t *fullscreen_override; /**< @brief An optional override picture which must have unscaled full-screen size, which overrides all other visibility, and which is generally slow */
    127122
    128         gfxr_pic_t *pic, *pic_unscaled; /* The background picture and its unscaled equivalent */
    129         rect_t pic_port_bounds;  /* Picture port bounds */
     123        gfxr_pic_t *pic, *pic_unscaled; /**< @brief The background picture and its unscaled equivalent */
     124        rect_t pic_port_bounds;  /**< @brief Picture port bounds */
    130125
    131         DirtyRectList _dirtyRects; /* Dirty rectangles */
     126        DirtyRectList _dirtyRects; /**< @brief Dirty rectangles */
    132127};
    133128
    134129
    135 /**************************/
    136 /* Fundamental operations */
    137 /**************************/
    138 
    139 int gfxop_init(int version, bool isVGA, GfxState *state, gfx_options_t *options, ResourceManager *resManager,
    140                            int xfact = 1, int yfact = 1, gfx_color_mode_t bpp = GFX_COLOR_MODE_INDEX);
    141 /* Initializes a graphics mode
    142 ** Parameters: (int) version: The interpreter version
    143 **             (GfxState *) state: The state to initialize
    144 **             (int x int) xfact, yfact: Horizontal and vertical scale factors
    145 **             (gfx_color_mode_t) bpp: Bytes per pixel to initialize with, or
    146 **                                     0 (GFX_COLOR_MODE_AUTO) to auto-detect
    147 **             (gfx_options_t *) options: Rendering options
    148 **             (void *) misc_info: Additional information for the interpreter
    149 **                      part of the resource loader
    150 ** Returns   : (int) GFX_OK on success, GFX_ERROR if that particular mode is
    151 **                   unavailable, or GFX_FATAL if the graphics driver is unable
    152 **                   to provide any useful graphics support
    153 */
    154130
     131/** @name Fundamental operations */
     132/** @{ */
     133
     134/**
     135 * @brief Initializes a graphics mode.
     136 *
     137 * @param[in] version           The interpreter version
     138 * @param[in] isVGA                     true if using VGA resolution
     139 * @param[in] state                     The state to initialize
     140 * @param[in] xfact                     Horizontal scale factor
     141 * @param[in] yfact                     Vertical scale factors
     142 * @param[in] bpp                       Bytes per pixel to initialize with, or 0
     143 *                                                      (GFX_COLOR_MODE_AUTO) to auto-detect
     144 * @param[in] options           Rendering options
     145 * @param[in] resManager        Resource manager to use
     146 * @return                                      GFX_OK on success, GFX_ERROR if that particular mode
     147 *                                                      is unavailable, or GFX_FATAL if the graphics driver
     148 *                                                      is unable to provide any useful graphics support
     149 */
     150int gfxop_init(int version, bool isVGA, GfxState *state, gfx_options_t *options,
     151        ResourceManager *resManager, int xfact = 1, int yfact = 1,
     152        gfx_color_mode_t bpp = GFX_COLOR_MODE_INDEX);
     153
     154/**
     155 * @brief Deinitializes a currently active driver.
     156 *
     157 * @param[in] state     The state encapsulating the driver in question
     158 * @return                      GFX_OK
     159 */
    155160int gfxop_exit(GfxState *state);
    156 /* Deinitializes a currently active driver
    157 ** Parameters: (GfxState *) state: The state encapsulating the driver in question
    158 ** Returns   : (int) GFX_OK
    159 */
    160161
     162/**
     163 * @brief Calculates a bit mask calculated from some pixels on the specified
     164 * map.
     165 *
     166 * @param[in] state     The state containing the pixels to scan
     167 * @param[in] area      The area to check
     168 * @param[in] map       The GFX_MASKed map(s) to test
     169 * @return                      An integer value where, for each 0 <= i <= 15, bit i is set
     170 *                                      iff     there exists a map for which the corresponding bit was
     171 *                                      set in the 'map' parameter and for which there exists a
     172 *                                      pixel within the specified area so that the pixel's lower 4
     173 *                                      bits, interpreted as an integer value, equal i. (Short
     174 *                                      version: This is an implementation of "on_control()").
     175 */
    161176int gfxop_scan_bitmask(GfxState *state, rect_t area, gfx_map_mask_t map);
    162 /* Calculates a bit mask calculated from some pixels on the specified map
    163 ** Parameters: (GfxState *) state: The state containing the pixels to scan
    164 **             (rect_t) area: The area to check
    165 **             (gfx_map_mask_t) map: The GFX_MASKed map(s) to test
    166 ** Returns   : (int) An integer value where, for each 0<=i<=15, bit #i is set
    167 **             iff there exists a map for which the corresponding bit was set
    168 **             in the 'map' parameter and for which there exists a pixel within
    169 **             the specified area so that the pixel's lower 4 bits, interpreted
    170 **             as an integer value, equal i.
    171 ** (Short version: This is an implementation of "on_control()").
    172 */
    173177
     178/**
     179 * @brief Sets the currently visible map.
     180 *
     181 * 'visible_map' can be any of GFX_MASK_VISUAL, GFX_MASK_PRIORITY and
     182 * GFX_MASK_CONTROL; the appropriate map (as far as its contents are known to
     183 * the graphics subsystem) is then subsequently drawn to the screen at each
     184 * update. If this is set to anything other than GFX_MASK_VISUAL, slow
     185 * full-screen updates are performed. Mostly useful for debugging. The screen
     186 * needs to be updated for the changes to take effect.
     187 *
     188 * @param[in] state     The state to modify
     189 * @param[in] map       The GFX_MASK to set
     190 * @return                      GFX_OK, or GFX_ERROR if map was invalid
     191 */
    174192int gfxop_set_visible_map(GfxState *state, gfx_map_mask_t map);
    175 /* Sets the currently visible map
    176 ** Parameters: (GfxState *) state: The state to modify
    177 **             (gfx_map_mask_t) map: The GFX_MASK to set
    178 ** Returns   : (int) GFX_OK, or GFX_ERROR if map was invalid
    179 ** 'visible_map' can be any of GFX_MASK_VISUAL, GFX_MASK_PRIORITY and GFX_MASK_CONTROL; the appropriate
    180 ** map (as far as its contents are known to the graphics subsystem) is then subsequently drawn to the
    181 ** screen at each update. If this is set to anything other than GFX_MASK_VISUAL, slow full-screen updates
    182 ** are performed. Mostly useful for debugging.
    183 ** The screen needs to be updated for the changes to take effect.
    184 */
    185193
     194/**
     195 * @brief Sets a new clipping zone.
     196 *
     197 * @param[in] state     The affected state
     198 * @param[in] zone      The new clipping zone
     199 * @return                      GFX_OK
     200 */
    186201int gfxop_set_clip_zone(GfxState *state, rect_t zone);
    187 /* Sets a new clipping zone
    188 ** Parameters: (GfxState *) state: The affected state
    189 **             (rect_t) zone: The new clipping zone
    190 ** Returns   : (int) GFX_OK
    191 */
     202/** @} */
     203
    192204
    193 /******************************/
    194 /* Generic drawing operations */
    195 /******************************/
     205/** @name Generic drawing operations */
     206/** @{ */
    196207
     208/**
     209 * @brief Renders a clipped line to the back buffer.
     210 *
     211 * @param[in] state                     The state affected
     212 * @param[in] start                     Starting point of the line
     213 * @param[in] end                       End point of the line
     214 * @param[in] color                     The color to use for drawing
     215 * @param[in] line_mode         Any valid line mode to use
     216 * @param[in] line_style        The line style to use
     217 * @return                                      GFX_OK or GFX_FATAL
     218 */
    197219int gfxop_draw_line(GfxState *state,
    198220        Common::Point start, Common::Point end, gfx_color_t color,
    199221        gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    200 /* Renders a clipped line to the back buffer
    201 ** Parameters: (GfxState *) state: The state affected
    202 **             (Common::Point) start: Starting point of the line
    203 **             (Common::Point) end: End point of the line
    204 **             (gfx_color_t) color: The color to use for drawing
    205 **             (gfx_line_mode_t) line_mode: Any valid line mode to use
    206 **             (gfx_line_style_t) line_style: The line style to use
    207 ** Returns   : (int) GFX_OK or GFX_FATAL
    208 */
    209222
    210 int gfxop_draw_rectangle(GfxState *state, rect_t rect, gfx_color_t color, gfx_line_mode_t line_mode,
    211         gfx_line_style_t line_style);
    212 /* Draws a non-filled rectangular box to the back buffer
    213 ** Parameters: (GfxState *) state: The affected state
    214 **             (rect_t) rect: The rectangular area the box is drawn to
    215 **             (gfx_color_t) color: The color the box is to be drawn in
    216 **             (gfx_line_mode_t) line_mode: The line mode to use
    217 **             (gfx_line_style_t) line_style: The line style to use for the box
    218 ** Returns   : (int) GFX_OK or GFX_FATAL
    219 ** Boxes drawn in thin lines will surround the minimal area described by rect.
    220 */
     223/**
     224 * @brief Draws a non-filled rectangular box to the back buffer.
     225 *
     226 * Boxes drawn in thin lines will surround the minimal area described by rect.
     227 *
     228 * @param[in] state                     The affected state
     229 * @param[in] rect                      The rectangular area the box is drawn to
     230 * @param[in] color                     The color the box is to be drawn in
     231 * @param[in] line_mode         The line mode to use
     232 * @param[in] line_style        The line style to use for the box
     233 * @return                                      GFX_OK or GFX_FATAL
     234 */
     235int gfxop_draw_rectangle(GfxState *state, rect_t rect, gfx_color_t color,
     236        gfx_line_mode_t line_mode, gfx_line_style_t line_style);
    221237
    222 int gfxop_draw_box(GfxState *state, rect_t box, gfx_color_t color1, gfx_color_t color2,
    223         gfx_box_shade_t shade_type);
    224 /* Draws a filled box to the back buffer
    225 ** Parameters: (GfxState *) state: The affected state
    226 **             (rect_t) box: The area to draw to
    227 **             (gfx_color_t) color1: The primary color to use for drawing
    228 **             (gfx_color_t) color2: The secondary color to draw in
    229 **             (gfx_box_shade_t) shade_type: The shading system to use
    230 **                               (e.g. GFX_BOX_SHADE_FLAT)
    231 ** Returns   : (int) GFX_OK or GFX_FATAL
    232 ** The draw mask, control, and priority values are derived from color1.
    233 */
     238/**
     239 * @brief Draws a filled box to the back buffer.
     240 *
     241 * The draw mask, control, and priority values are derived from color1.
     242 *
     243 * @param[in] state                     The affected state
     244 * @param[in] box                       The area to draw to
     245 * @param[in] color1            The primary color to use for drawing
     246 * @param[in] color2            The secondary color to draw in
     247 * @param[in] shade_type        The shading system to use (e.g. GFX_BOX_SHADE_FLAT)
     248 * @return                                      GFX_OK or GFX_FATAL
     249 */
     250int gfxop_draw_box(GfxState *state, rect_t box, gfx_color_t color1,
     251        gfx_color_t color2, gfx_box_shade_t shade_type);
    234252
     253/**
     254 * @brief Fills a box in the back buffer with a specific color.
     255 *
     256 * This is a simple wrapper function for gfxop_draw_box
     257 *
     258 * @param[in] state     The state to draw to
     259 * @param[in] box       The box to fill
     260 * @param[in] color     The color to use for filling
     261 * @return                      GFX_OK or GFX_FATAL
     262 */
    235263int gfxop_fill_box(GfxState *state, rect_t box, gfx_color_t color);
    236 /* Fills a box in the back buffer with a specific color
    237 ** Parameters: (GfxState *) state: The state to draw to
    238 **             (rect_t) box: The box to fill
    239 **             (gfx_color_t) color: The color to use for filling
    240 ** Returns   : (int) GFX_OK or GFX_FATAL
    241 ** This is a simple wrapper function for gfxop_draw_box
    242 */
    243264
     265/**
     266 * @brief Copies a box from the static buffer to the back buffer.
     267 *
     268 * @param[in] state     The affected state
     269 * @param[in] box       The box to propagate from the static buffer
     270 * @return                      GFX_OK or GFX_FATAL
     271 */
    244272int gfxop_clear_box(GfxState *state, rect_t box);
    245 /* Copies a box from the static buffer to the back buffer
    246 ** Parameters: (GfxState *) state: The affected state
    247 **             (rect_t) box: The box to propagate from the static buffer
    248 ** Returns   : (int) GFX_OK or GFX_FATAL
    249 */
    250273
    251274
     275/**
     276 * @brief Updates all dirty rectangles.
     277 *
     278 * In order to track dirty rectangles, they must be enabled in the options. This
     279 * function instructs the resource manager to free all tagged data on certain
     280 * occasions (see gfxop_new_pic).
     281 *
     282 * @param[in] state     The relevant state
     283 * @return                      GFX_OK or GFX_FATAL if reported by the driver
     284 */
    252285int gfxop_update(GfxState *state);
    253 /* Updates all dirty rectangles
    254 ** Parameters: (GfxState) *state: The relevant state
    255 ** Returns   : (int) GFX_OK or GFX_FATAL if reported by the driver
    256 ** In order to track dirty rectangles, they must be enabled in the options.
    257 ** This function instructs the resource manager to free all tagged data
    258 ** on certain occasions (see gfxop_new_pic).
    259 */
    260286
    261287
     288/**
     289 * @brief Propagates a box from the back buffer to the front (visible) buffer.
     290 *
     291 * This function instructs the resource manager to free all tagged data on
     292 * certain occasions (see gfxop_new_pic). When called with dirty rectangle
     293 * management enabled, it will automatically propagate all dirty rectangles as
     294 * well, UNLESS dirty frame accounting has been disabled explicitly.
     295 *
     296 * @param[in] state     The affected state
     297 * @param[in] box       The box to propagate to the front buffer
     298 * @return                      GFX_OK or GFX_FATAL
     299 */
    262300int gfxop_update_box(GfxState *state, rect_t box);
    263 /* Propagates a box from the back buffer to the front (visible) buffer
    264 ** Parameters: (GfxState *) state: The affected state
    265 **             (rect_t) box: The box to propagate to the front buffer
    266 ** Returns   : (int) GFX_OK or GFX_FATAL
    267 ** This function instructs the resource manager to free all tagged data
    268 ** on certain occasions (see gfxop_new_pic).
    269 ** When called with dirty rectangle management enabled, it will automatically
    270 ** propagate all dirty rectangles as well, UNLESS dirty frame accounting has
    271 ** been disabled explicitly.
    272 */
    273301
     302/**
     303 * @brief Enables dirty frame accounting.
     304 *
     305 * Dirty frame accounting is enabled by default.
     306 *
     307 * @param[in] state     The state dirty frame accounting is to be enabled in
     308 * @return                      GFX_OK or GFX_ERROR if state was invalid
     309 */
    274310int gfxop_enable_dirty_frames(GfxState *state);
    275 /* Enables dirty frame accounting
    276 ** Parameters: (GfxState *) state: The state dirty frame accounting is to be enabled in
    277 ** Returns   : (int) GFX_OK or GFX_ERROR if state was invalid
    278 ** Dirty frame accounting is enabled by default.
    279 */
    280311
     312/**
     313 * @brief Disables dirty frame accounting.
     314 *
     315 * @param[in] state     The state dirty frame accounting is to be disabled in
     316 * @return                      GFX_OK or GFX_ERROR if state was invalid
     317 */
    281318int gfxop_disable_dirty_frames(GfxState *state);
    282 /* Disables dirty frame accounting
    283 ** Parameters: (GfxState *) state: The state dirty frame accounting is to be disabled in
    284 ** Returns   : (int) GFX_OK or GFX_ERROR if state was invalid
    285 */
     319/** @} */
    286320
    287321
    288 /********************/
    289 /* Color operations */
    290 /********************/
    291 
    292 int gfxop_set_color(GfxState *state, gfx_color_t *color, int r, int g, int b, int a,
    293         int priority, int control);
    294 /* Maps an r/g/b value to a color and sets a gfx_color_t structure
    295 ** Parameters: (GfxState *) state: The current state
    296 **             (gfx_color_t *) color: Pointer to the structure to write to
    297 **             (int x int x int) r,g,b: The red/green/blue color intensity values
    298 **                               of the result color (0x00 (minimum) to 0xff (max))
    299 **                               If any of these values is less than zero, the
    300 **                               resulting color will not affect the visual map when
    301 **                               used for drawing
    302 **             (int) a: The alpha (transparency) value, with 0x00 meaning absolutely
    303 **                      opaque and 0xff meaning fully transparent. Alpha blending support
    304 **                      is optional for drivers, so these are the only two values that
    305 **                      are guaranteed to work as intended. Any value in between them
    306 **                      must guarantee the following opaqueness:
    307 **                      opaqueness(x-1) >= opaqueness(x) >= opaqueness (x+1)
    308 **                      (i.e. ([0,255], less-transparent-than) must define a partial order)
    309 **             (int) priority: The priority to use for drawing, or -1 for none
    310 **             (int) control: The control to use for drawing, or -1 to disable drawing to the
    311 **                            control map
    312 ** Returns   : (int) GFX_OK or GFX_ERROR if state is invalid
    313 ** In palette mode, this may allocate a new color. Use gfxop_free_color() described below to
    314 ** free that color.
    315 */
     322/** @name Color operations */
     323/** @{ */
     324
     325/**
     326 * @brief Maps an r/g/b value to a color and sets a gfx_color_t structure.
     327 *
     328 * In palette mode, this may allocate a new color. Use gfxop_free_color() to
     329 * free that color. If any of the r/g/b values are less than zero, the resulting
     330 * color will not affect the visual map when used for drawing
     331 *
     332 * @param[in] state             The current state
     333 * @param[in] color             Pointer to the structure to write to
     334 * @param[in] r                 The red color intensity values of the result color
     335 * @param[in] g                 The green color intensity values of the result color
     336 * @param[in] b                 The blue color intensity values of the result color
     337 * @param[in] a                 The alpha (transparency) value, with 0x00 meaning
     338 *                                              absolutely opaque and 0xff meaning fully transparent.
     339 *                                              Alpha blending support is optional for drivers, so these
     340 *                                              are the only two values that are guaranteed to work as
     341 *                                              intended. Any value in between them must guarantee the
     342 *                                              following opaqueness: opaqueness(x-1) >= opaqueness(x)
     343 *                                              >= opaqueness (x+1) (i.e. ([0,255],
     344 *                                              less-transparent-than) must define a partial order)
     345 * @param[in] priority  The priority to use for drawing, or -1 for none
     346 * @param[in] control   The control to use for drawing, or -1 to disable drawing
     347 *                                              to the control map
     348 * @return                              GFX_OK or GFX_ERROR if state is invalid
     349 */
     350int gfxop_set_color(GfxState *state, gfx_color_t *color, int r, int g, int b,
     351        int a, int priority, int control);
    316352
     353/**
     354 * @brief Designates a color as a 'system color'.
     355 *
     356 * system colors are permanent colors that cannot be deallocated. as such, they must be used with caution.
     357 *
     358 * @param[in] state     The affected state
     359 * @param[in] index     The index for the new system color
     360 * @param[in] color     The color to designate as a system color
     361 * @return                      GFX_OK or GFX_ERROR if state is invalid
     362 */
    317363int gfxop_set_system_color(GfxState *state, unsigned int index, gfx_color_t *color);
    318 /* Designates a color as a 'system color'
    319 ** Parameters: (GfxState *) state: The affected state
    320 **             (unsigned int) index: The index for the new system color
    321 **             (gfx_color_t *) color: The color to designate as a system color
    322 ** Returns   : (int) GFX_OK or GFX_ERROR if state is invalid
    323 ** System colors are permanent colors that cannot be deallocated. As such, they must be used
    324 ** with caution.
    325 */
    326364
     365/**
     366 * @brief Frees a color allocated by gfxop_set_color().
     367 *
     368 * This function is a no-op in non-index mode, or if color is a system color.
     369 *
     370 * @param[in] state     The state affected
     371 * @param[in] color     The color to de-allocate
     372 * @return                      GFX_OK or GFX_ERROR if state is invalid
     373 */
    327374int gfxop_free_color(GfxState *state, gfx_color_t *color);
    328 /* Frees a color allocated by gfxop_set_color()
    329 ** Parmaeters: (GfxState *) state: The state affected
    330 **             (gfx_color_t *) color: The color to de-allocate
    331 ** Returns   : (int) GFX_OK or GFX_ERROR if state is invalid
    332 ** This function is a no-op in non-index mode, or if color is a system color.
    333 */
    334 
     375/** @} */
    335376
    336 /**********************/
    337 /* Pointer and IO ops */
    338 /**********************/
     377/** @name Pointer and IO ops */
     378/** @{ */
    339379
     380/**
     381 * @brief Suspends program execution for the specified amount of milliseconds.
     382 *
     383 * The mouse pointer will be redrawn continually, if applicable
     384 *
     385 * @param[in] state     The state affected
     386 * @param[in] msecs     The amount of milliseconds to wait
     387 * @return                      GFX_OK or GFX_ERROR
     388 */
    340389int gfxop_sleep(GfxState *state, uint32 msecs);
    341 /* Suspends program execution for the specified amount of milliseconds
    342 ** Parameters: (GfxState *) state: The state affected
    343 **             (uint32) usecs: The amount of milliseconds to wait
    344 ** Returns   : (int) GFX_OK or GFX_ERROR
    345 ** The mouse pointer will be redrawn continually, if applicable
    346 */
    347390
     391/**
     392 * @brief Sets the mouse pointer to a cursor resource.
     393 *
     394 * @param[in] state     The affected state
     395 * @param[in] nr        Number of the cursor resource to use
     396 * @return                      GFX_OK, GFX_ERROR if the resource did not exist and was not
     397 *                                      GFXOP_NO_POINTER, or GFX_FATAL on fatal error conditions.
     398 *                                      Use nr = GFX_NO_POINTER to disable the mouse pointer
     399 *                                      (default).
     400 */
    348401int gfxop_set_pointer_cursor(GfxState *state, int nr);
    349 /* Sets the mouse pointer to a cursor resource
    350 ** Parameters: (GfxState *) state: The affected state
    351 **             (int) nr: Number of the cursor resource to use
    352 ** Returns   : (int) GFX_OK, GFX_ERROR if the resource did not
    353 **                   exist and was not GFXOP_NO_POINTER, or GFX_FATAL on
    354 **                   fatal error conditions.
    355 ** Use nr = GFX_NO_POINTER to disable the mouse pointer (default).
    356 */
    357402
     403/**
     404 * @brief Sets the mouse pointer to a view resource.
     405 *
     406 * Use gfxop_set_pointer_cursor(state, GFXOP_NO_POINTER) to disable the pointer.
     407 *
     408 * @param[in] state             The affected state
     409 * @param[in] nr                Number of the view resource to use
     410 * @param[in] loop              View loop to use
     411 * @param[in] cel               View cel to use
     412 * @param[in] hotspot   Manually set hotspot to use, or NULL for default.
     413 * @return                              GFX_OK or GFX_FATAL
     414 */
    358415int gfxop_set_pointer_view(GfxState *state, int nr, int loop, int cel, Common::Point *hotspot);
    359 /* Sets the mouse pointer to a view resource
    360 ** Parameters: (GfxState *) state: The affected state
    361 **             (int) nr: Number of the view resource to use
    362 **             (int) loop: View loop to use
    363 **             (int) cel: View cel to use
    364 **             (Common::Point *) hotspot: Manually set hotspot to use, or NULL for default.
    365 ** Returns   : (int) GFX_OK or GFX_FATAL
    366 ** Use gfxop_set_pointer_cursor(state, GFXOP_NO_POINTER) to disable the
    367 ** pointer.
    368 */
    369416
     417/**
     418 * @brief Teleports the mouse pointer to a specific position.
     419 *
     420 * Depending on the graphics driver, this operation may be without any effect
     421 *
     422 * @param[in] state     The state the pointer is in
     423 * @param[in] pos       The position to teleport it to
     424 * @return                      Any error code or GFX_OK
     425 */
    370426int gfxop_set_pointer_position(GfxState *state, Common::Point pos);
    371 /* Teleports the mouse pointer to a specific position
    372 ** Parameters: (GfxState *) state: The state the pointer is in
    373 **             (Common::Point) pos: The position to teleport it to
    374 ** Returns   : (int) Any error code or GFX_OK
    375 ** Depending on the graphics driver, this operation may be without
    376 ** any effect
    377 */
    378427
     428/**
     429 * @brief Retrieves the next input event from the driver.
     430 *
     431 * @param[in] state     The affected state
     432 * @param[in] mask      The event mask to poll from (see uinput.h)
     433 * @return                      The next event in the driver's event queue, or a NONE event
     434 *                                      if no event matching the mask was found.
     435 */
    379436sci_event_t gfxop_get_event(GfxState *state, unsigned int mask);
    380 /* Retrieves the next input event from the driver
    381 ** Parameters: (GfxState *) state: The affected state
    382 **             (int) mask: The event mask to poll from (see uinput.h)
    383 ** Returns   : (sci_event_t) The next event in the driver's event queue, or
    384 **             a NONE event if no event matching the mask was found.
    385 */
     437/** @} */
    386438
     439/** @name View operations */
     440/** @{ */
    387441
    388 /*******************/
    389 /* View operations */
    390 /*******************/
    391 
     442/**
     443 * @brief Determines the number of loops associated with a view.
     444 *
     445 * @param[in] state     The state to use
     446 * @param[in] nr        Number of the view to investigate
     447 * @return                      The number of loops, or GFX_ERROR if the view didn't exist
     448 */
    392449int gfxop_lookup_view_get_loops(GfxState *state, int nr);
    393 /* Determines the number of loops associated with a view
    394 ** Parameters: (GfxState *) state: The state to use
    395 **             (int) nr: Number of the view to investigate
    396 ** Returns   : (int) The number of loops, or GFX_ERROR if the view didn't exist
    397 */
    398450
     451/**
     452 * @brief Determines the number of cels associated stored in a loop.
     453 *
     454 * @param[in] state     The state to look up in
     455 * @param[in] nr        Number of the view to look up in
     456 * @param[in] loop      Number of the loop the number of cels of are to be
     457 *                                      investigated
     458 * @return                      The number of cels in that loop, or GFX_ERROR if either the
     459 *                                      view or the loop didn't exist
     460 */
    399461int gfxop_lookup_view_get_cels(GfxState *state, int nr, int loop);
    400 /* Determines the number of cels associated stored in a loop
    401 ** Parameters: (GfxState *) state: The state to look up in
    402 **             (int) nr: Number of the view to look up in
    403 **             (int) loop: Number of the loop the number of cels of
    404 **                         are to  be investigated
    405 ** Returns   : (int) The number of cels in that loop, or GFX_ERROR if either
    406 **                   the view or the loop didn't exist
    407 */
    408462
     463/**
     464 * @brief Clips the view/loop/cel position of a cel.
     465 *
     466 * *loop is clipped first, then *cel. The resulting setup will be a valid view
     467 * configuration.
     468 *
     469 * @param[in] state     The state to use
     470 * @param[in] nr        Number of the view to use
     471 * @param[in] loop      Pointer to the variable storing the loop number to verify
     472 * @param[in] cel       Pointer to the variable storing the cel number to check
     473 * @return                      GFX_OK or GFX_ERROR if the view didn't exist
     474 */
    409475int gfxop_check_cel(GfxState *state, int nr, int *loop, int *cel);
    410 /* Clips the view/loop/cel position of a cel
    411 ** Parameters: (GfxState *) state: The state to use
    412 **             (int) nr: Number of the view to use
    413 **             (int *) loop: Pointer to the variable storing the loop
    414 **                           number to verify
    415 **             (int *) cel: Pointer to the variable storing the cel
    416 **                          number to check
    417 ** Returns   : (int) GFX_OK or GFX_ERROR if the view didn't exist
    418 ** *loop is clipped first, then *cel. The resulting setup will be a valid
    419 ** view configuration.
    420 */
    421476
     477/**
     478 * @brief Resets loop/cel values to zero if they have become invalid.
     479 *
     480 * @param[in] state     The state to use
     481 * @param[in] nr        Number of the view to use
     482 * @param[in] loop      Pointer to the variable storing the loop number to verify
     483 * @param[in] cel       Pointer to the variable storing the cel number to check
     484 * @return                      GFX_OK or GFX_ERROR if the view didn't exist *loop is
     485 *                                      clipped first, then *cel. The resulting setup will be a
     486 *                                      valid view configuration.
     487 */
    422488int gfxop_overflow_cel(GfxState *state, int nr, int *loop, int *cel);
    423 /* Resets loop/cel values to zero if they have become invalid
    424 ** Parameters: (GfxState *) state: The state to use
    425 **             (int) nr: Number of the view to use
    426 **             (int *) loop: Pointer to the variable storing the loop
    427 **                           number to verify
    428 **             (int *) cel: Pointer to the variable storing the cel
    429 **                          number to check
    430 ** Returns   : (int) GFX_OK or GFX_ERROR if the view didn't exist
    431 ** *loop is clipped first, then *cel. The resulting setup will be a valid
    432 ** view configuration.
    433 */
    434489
     490/**
     491 * @brief Retrieves the width and height of a cel.
     492 *
     493 * @param[in] state             The state to use
     494 * @param[in] nr                Number of the view
     495 * @param[in] loop              Loop number to examine
     496 * @param[in] cel               The cel (inside the loop) to look up
     497 * @param[in] width             The variable the width will be stored in
     498 * @param[in] height    The variable the height will be stored in
     499 * @param[in] offset    The variable the cel's x/y offset will be stored in
     500 * @return                              GFX_OK if the lookup succeeded, GFX_ERROR if the
     501 *                                              nr/loop/cel combination was invalid
     502 */
    435503int gfxop_get_cel_parameters(GfxState *state, int nr, int loop, int cel,
    436504        int *width, int *height, Common::Point *offset);
    437 /* Retrieves the width and height of a cel
    438 ** Parameters: (GfxState *) state: The state to use
    439 **             (int) nr: Number of the view
    440 **             (int) loop: Loop number to examine
    441 **             (int) cel: The cel (inside the loop) to look up
    442 **             (int *) width: The variable the width will be stored in
    443 **             (int *) height: The variable the height will be stored in
    444 **             (Common::Point *) offset: The variable the cel's x/y offset will be stored in
    445 ** Returns   : (int) GFX_OK if the lookup succeeded, GFX_ERROR if the nr/loop/cel
    446 **             combination was invalid
    447 */
    448505
    449 int gfxop_draw_cel(GfxState *state, int nr, int loop, int cel, Common::Point pos,
    450         gfx_color_t color, int palette);
    451 /* Draws (part of) a cel to the back buffer
    452 ** Parameters: (GfxState *) state: The state encapsulating the driver to draw with
    453 **             (int) nr: Number of the view to draw
    454 **             (int) loop: Loop of the cel to draw
    455 **             (int) cel: The cel number of the cel to draw
    456 **             (Common::Point) pos: The positino the cel is to be drawn to
    457 **             (gfx_color_t color): The priority and control values to use for drawing
    458 **             (int) palette: The palette to use
    459 ** Returns   : (int) GFX_OK or GFX_FATAL
    460 */
     506/**
     507 * @brief Draws (part of) a cel to the back buffer.
     508 *
     509 * @param[in] state             The state encapsulating the driver to draw with
     510 * @param[in] nr                Number of the view to draw
     511 * @param[in] loop              Loop of the cel to draw
     512 * @param[in] cel               The cel number of the cel to draw
     513 * @param[in] pos               The positino the cel is to be drawn to
     514 * @param[in] color             The priority and control values to use for drawing
     515 * @param[in] palette   The palette to use
     516 * @return                              GFX_OK or GFX_FATAL
     517 */
     518int gfxop_draw_cel(GfxState *state, int nr, int loop, int cel,
     519        Common::Point pos, gfx_color_t color, int palette);
    461520
    462521
    463 int gfxop_draw_cel_static(GfxState *state, int nr, int loop, int cel, Common::Point pos,
    464         gfx_color_t color, int palette);
    465 /* Draws a cel to the static buffer; no clipping is performed
    466 ** Parameters: (GfxState *) state: The state encapsulating the driver to draw with
    467 **             (int) nr: Number of the view to draw
    468 **             (int) loop: Loop of the cel to draw
    469 **             (int) cel: The cel number of the cel to draw
    470 **             (Common::Point) pos: The positino the cel is to be drawn to
    471 **             (gfx_color_t color): The priority and control values to use for drawing
    472 **             (int) palette: The palette to use
    473 ** Returns   : (int) GFX_OK or GFX_FATAL
    474 ** Let me repeat, no clipping (except for the display borders) is performed.
    475 */
     522/**
     523 * @brief Draws a cel to the static buffer; no clipping is performed.
     524 *
     525 * No clipping (except for the display borders) is performed.
     526 *
     527 * @param[in] state             The state encapsulating the driver to draw with
     528 * @param[in] nr                Number of the view to draw
     529 * @param[in] loop              Loop of the cel to draw
     530 * @param[in] cel               The cel number of the cel to draw
     531 * @param[in] pos               The positino the cel is to be drawn to
     532 * @param[in] color             The priority and control values to use for drawing
     533 * @param[in] palette   The palette to use
     534 * @return                              GFX_OK or GFX_FATAL
     535 */
     536int gfxop_draw_cel_static(GfxState *state, int nr, int loop, int cel,
     537        Common::Point pos, gfx_color_t color, int palette);
    476538
    477539
    478 int gfxop_draw_cel_static_clipped(GfxState *state, int nr, int loop, int cel, Common::Point pos,
    479         gfx_color_t color, int palette);
    480 /* Draws (part of) a clipped cel to the static buffer
    481 ** Parameters: (GfxState *) state: The state encapsulating the driver to draw with
    482 **             (int) nr: Number of the view to draw
    483 **             (int) loop: Loop of the cel to draw
    484 **             (int) cel: The cel number of the cel to draw
    485 **             (Common::Point) pos: The positino the cel is to be drawn to
    486 **             (gfx_color_t color): The priority and control values to use for drawing
    487 **             (int) palette: The palette to use
    488 ** Returns   : (int) GFX_OK or GFX_FATAL
    489 ** This function does clip.
    490 */
     540/**
     541 * @brief Draws (part of) a clipped cel to the static buffer.
     542 *
     543 * This function does clip.
     544 *
     545 * @param[in] state             The state encapsulating the driver to draw with
     546 * @param[in] nr                Number of the view to draw
     547 * @param[in] loop              Loop of the cel to draw
     548 * @param[in] cel               The cel number of the cel to draw
     549 * @param[in] pos               The positino the cel is to be drawn to
     550 * @param[in] color             The priority and control values to use for drawing
     551 * @param[in] palette   The palette to use
     552 * @return                              GFX_OK or GFX_FATAL
     553 */
     554int gfxop_draw_cel_static_clipped(GfxState *state, int nr, int loop, int cel,
     555        Common::Point pos, gfx_color_t color, int palette);
     556/** @} */
    491557
    492558
    493 /******************/
    494 /* Pic operations */
    495 /******************/
    496 /* These operations are exempt from clipping */
     559/** @name Pic operations
     560 * These operations are exempt from clipping */
     561/** @{ */
    497562
     563/**
     564 * @brief Draws a pic and writes it over the static buffer.
     565 *
     566 * This function instructs the resource manager to tag all data as "unused".
     567 * See the resource manager tag functions for a full description.
     568 *
     569 * @param[in] state                             The state affected
     570 * @param[in] nr                                Number of the pic to draw
     571 * @param[in] flags                             Interpreter-dependant flags to use for drawing
     572 * @param[in] default_palette   The default palette for drawing
     573 * @return                                              GFX_OK or GFX_FATAL
     574 */
    498575int gfxop_new_pic(GfxState *state, int nr, int flags, int default_palette);
    499 /* Draws a pic and writes it over the static buffer
    500 ** Parameters: (GfxState *) state: The state affected
    501 **             (int) nr: Number of the pic to draw
    502 **             (int) flags: Interpreter-dependant flags to use for drawing
    503 **             (int) default_palette: The default palette for drawing
    504 ** Returns   : (int) GFX_OK or GFX_FATAL
    505 ** This function instructs the resource manager to tag all data as "unused".
    506 ** See the resource manager tag functions for a full description.
    507 */
    508576
     577/**
     578 * @brief Retrieves all meta-information assigned to the current pic.
     579 *
     580 * @param[in] state     The state affected
     581 * @return                      NULL if the pic doesn't exist or has no meta-information,
     582 *                                      the meta-info otherwise. This meta-information is referred
     583 *                                      to as 'internal data' in the pic code
     584 */
    509585int *gfxop_get_pic_metainfo(GfxState *state);
    510 /* Retrieves all meta-information assigned to the current pic
    511 ** Parameters: (GfxState *) state: The state affected
    512 ** Returns   : (int *) NULL if the pic doesn't exist or has no meta-information,
    513 **             the meta-info otherwise
    514 ** This meta-information is referred to as 'internal data' in the pic code
    515 */
    516586
     587/**
     588 * @brief Adds a pic to the static buffer.
     589 *
     590 * @param[in] state                             The state affected
     591 * @param[in] nr                                Number of the pic to add
     592 * @param[in] flags                             Interpreter-dependant flags to use for drawing
     593 * @param[in] default_palette   The default palette for drawing
     594 * @return                                              GFX_OK or GFX_FATAL
     595 */
    517596int gfxop_add_to_pic(GfxState *state, int nr, int flags, int default_palette);
    518 /* Adds a pic to the static buffer
    519 ** Parameters: (GfxState *) state: The state affected
    520 **             (int) nr: Number of the pic to add
    521 **             (int) flags: Interpreter-dependant flags to use for drawing
    522 **             (int) default_palette: The default palette for drawing
    523 ** Returns   : (int) GFX_OK or GFX_FATAL
    524 */
    525 
     597/** @} */
    526598
    527599
     600/** @name Text operations */
     601/** @{ */
    528602
    529 /*******************/
    530 /* Text operations */
    531 /*******************/
    532 
    533 
     603/**
     604 * @brief Returns the fixed line height for one specified font.
     605 *
     606 * @param[in] state             The state to work on
     607 * @param[in] font_nr   Number of the font to inspect
     608 * @return                              GFX_ERROR, GFX_FATAL, or the font line height
     609 */
    534610int gfxop_get_font_height(GfxState *state, int font_nr);
    535 /* Returns the fixed line height for one specified font
    536 ** Parameters: (GfxState *) state: The state to work on
    537 **             (int) font_nr: Number of the font to inspect
    538 ** Returns   : (int) GFX_ERROR, GFX_FATAL, or the font line height
    539 */
    540611
     612/**
     613 * @brief Calculates the width and height of a specified text in a specified
     614 * font.
     615 *
     616 * @param[in]  state                    The state to use
     617 * @param[in]  font_nr                  Font number to use for the calculation
     618 * @param[in]  text                             The text to examine
     619 * @param[in]  flags                    ORred GFXR_FONT_FLAGs
     620 * @param[in]  maxwidth                 The maximum pixel width to allow for the text
     621 * @param[out] width                    The resulting width
     622 * @param[out] height                   The resulting height
     623 * @param[out] lines_nr                 Number of lines used in the text
     624 * @param[out] lineheight               Pixel height (SCI scale) of each text line
     625 * @param[out] lastline_width   Pixel offset (SCI scale) of the space after
     626 *                                                              the last character in the last line
     627 * @return                                              GFX_OK or GFX_ERROR if the font didn't exist
     628 */
    541629int gfxop_get_text_params(GfxState *state, int font_nr, const char *text,
    542630        int maxwidth, int *width, int *height, int flags,
    543631        int *lines_nr, int *lineheight, int *lastline_width);
    544 /* Calculates the width and height of a specified text in a specified font
    545 ** Parameters: (GfxState *) state: The state to use
    546 **             (int) font_nr: Font number to use for the calculation
    547 **             (const char *) text: The text to examine
    548 **             (int) flags: ORred GFXR_FONT_FLAGs
    549 **             (int) maxwidth: The maximum pixel width to allow for the text
    550 ** Returns   : (int) GFX_OK or GFX_ERROR if the font didn't exist
    551 **             (int) *width: The resulting width
    552 **             (int) *height: The resulting height
    553 **             (int) *lines_nr: Number of lines used in the text
    554 **             (int) *lineheight: Pixel height (SCI scale) of each text line
    555 **             (int) *lastline_wdith: Pixel offset (SCI scale) of the space
    556 **                   after the last character in the last line
    557 */
    558632
    559 TextHandle *gfxop_new_text(GfxState *state, int font_nr, const Common::String &text, int maxwidth,
    560         gfx_alignment_t halign, gfx_alignment_t valign, gfx_color_t color1,
    561         gfx_color_t color2, gfx_color_t bg_color, int flags);
    562 /* Generates a new text handle that can be used to draw any text
    563 ** Parameters: (GfxState *) state: The state to use
    564 **             (int) font_nr: Font number to use for the calculation
    565 **             (const char *) text: The text to examine
    566 **             (int) maxwidth: The maximum pixel width to allow for the text
    567 **             (gfx_alignment_t) halign: The horizontal text alignment
    568 **             (gfx_alignment_t) valign: The vertical text alignment
    569 **             (gfx_color_t x gfx_color_t) color1, color2: The text's foreground colors
    570 **                                         (the function will dither between those two)
    571 **             (gfx_color_t) bg_color: The background color
    572 **             (int) flags: ORred GFXR_FONT_FLAGs
    573 ** Returns   : (TextHandle *) A newly allocated TextHandle, or
    574 **             NULL if font_nr was invalid
    575 ** The control and priority values for the text will be extracted from color1.
    576 ** Note that the colors must have been allocated properly, or the text may display in
    577 ** incorrect colors.
    578 */
     633/**
     634 * @brief Generates a new text handle that can be used to draw any text.
     635 *
     636 * The control and priority values for the text will be extracted from color1.
     637 * Note that the colors must have been allocated properly, or the text may
     638 * display in incorrect colors.
     639 *
     640 * @param[in] state             The state to use
     641 * @param[in] font_nr   Font number to use for the calculation
     642 * @param[in] text              The text to examine
     643 * @param[in] maxwidth: The maximum pixel width to allow for the text
     644 * @param[in] halign    The horizontal text alignment
     645 * @param[in] valign    The vertical text alignment
     646 * @param[in] color1    The text's foreground colors (the function will dither
     647 *                                              between color1 and 2)
     648 * @param[in] color2    The text's foreground colors (the function will dither
     649 *                                              between color1 and 2)
     650 * @param[in] bg_color  The background color
     651 * @param[in] flags             ORred GFXR_FONT_FLAGs
     652 * @return                              A newly allocated TextHandle, or NULL if font_nr was
     653 *                                              invalid
     654 */
     655TextHandle *gfxop_new_text(GfxState *state, int font_nr,
     656        const Common::String &text, int maxwidth, gfx_alignment_t halign,
     657        gfx_alignment_t valign, gfx_color_t color1,     gfx_color_t color2,
     658        gfx_color_t bg_color, int flags);
    579659
     660/**
     661 * @brief Frees a previously allocated text handle and all related resources.
     662 *
     663 * @param[in] state             The state to use
     664 * @param[in] handle    The handle to free
     665 * @return                              GFX_OK
     666 */
    580667int gfxop_free_text(GfxState *state, TextHandle *handle);
    581 /* Frees a previously allocated text handle and all related resources
    582 ** Parameters: (GfxState *) state: The state to use
    583 **             (TextHandle *) handle: The handle to free
    584 ** Returns   : (int) GFX_OK
    585 */
    586668
     669/**
     670 * @brief Draws text stored in a text handle.
     671 *
     672 * @param[in] state             The target state
     673 * @param[in] handle    The text handle to use for drawing
     674 * @param[in] zone              The rectangular box to draw to. In combination with
     675 *                                              halign and valign, this defines where the text is drawn
     676 *                                              to.
     677 * @return                              GFX_OK or GFX_FATAL
     678 */
    587679int gfxop_draw_text(GfxState *state, TextHandle *handle, rect_t zone);
    588 /* Draws text stored in a text handle
    589 ** Parameters: (GfxState *) state: The target state
    590 **             (TextHandle *) handle: The text handle to use for drawing
    591 **             (rect_t) zone: The rectangular box to draw to. In combination with
    592 **                            halign and valign, this defines where the text is
    593 **                            drawn to.
    594 ** Returns   : (int) GFX_OK or GFX_FATAL
    595 */
     680/** @} */
    596681
    597682
    598 /****************************/
    599 /* Manual pixmap operations */
    600 /****************************/
     683/** @name Manual pixmap operations */
     684/** @{ */
    601685
     686/**
     687 * @brief Grabs a screen section from the back buffer and stores it in a pixmap.
     688 *
     689 * Obviously, this only affects the visual map
     690 *
     691 * @param[in] state     The affected state
     692 * @param[in] area      The area to grab
     693 * Returns                      A result pixmap, or NULL on error
     694 */
    602695gfx_pixmap_t *gfxop_grab_pixmap(GfxState *state, rect_t area);
    603 /* Grabs a screen section from the back buffer and stores it in a pixmap
    604 ** Parameters: (GfxState *) state: The affected state
    605 **             (rect_t) area: The area to grab
    606 ** Returns   : (gfx_pixmap_t *) A result pixmap, or NULL on error
    607 ** Obviously, this only affects the visual map
    608 */
    609696
    610 int gfxop_draw_pixmap(GfxState *state, gfx_pixmap_t *pxm, rect_t zone, Common::Point pos);
    611 /* Draws part of a pixmap to the screen
    612 ** Parameters: (GfxState *) state: The affected state
    613 **             (gfx_pixmap_t *) pxm: The pixmap to draw
    614 **             (rect_t) zone: The segment of the pixmap to draw
    615 **             (Common::Point) pos: The position the pixmap should be drawn to
    616 ** Returns   : (int) GFX_OK or any error code
    617 */
     697/**
     698 * @brief Draws part of a pixmap to the screen.
     699 *
     700 * @param[in] state     The affected state
     701 * @param[in] pxm       The pixmap to draw
     702 * @param[in] zone      The segment of the pixmap to draw
     703 * @param[in] pos       The position the pixmap should be drawn to
     704 * @return                      GFX_OK or any error code
     705 */
     706int gfxop_draw_pixmap(GfxState *state, gfx_pixmap_t *pxm, rect_t zone,
     707        Common::Point pos);
    618708
     709/**
     710 * @brief Frees a pixmap returned by gfxop_grab_pixmap().
     711 *
     712 * @param[in] state     The affected state
     713 * @param[in] pxm       The pixmap to free
     714 * @return                      GFX_OK, or GFX_ERROR if the state was invalid
     715 */
    619716int gfxop_free_pixmap(GfxState *state, gfx_pixmap_t *pxm);
    620 /* Frees a pixmap returned by gfxop_grab_pixmap()
    621 ** Parameters: (GfxState *) state: The affected state
    622 **             (gfx_pixmap_t *) pxm: The pixmap to free
    623 ** Returns   : (int) GFX_OK, or GFX_ERROR if the state was invalid
    624 */
     717/** @} */
    625718
    626 /******************************/
    627 /* Dirty rectangle operations */
    628 /******************************/
     719
     720/** @name Dirty rectangle operations */
     721/** @{ */
    629722
    630723/**
    631  * Adds a dirty rectangle to 'base' according to a strategy.
    632  * @param list          the list to add to
    633  * @param box           the dirty frame to addable
    634  * @param strategy      the dirty frame heuristic to use (see gfx_options.h)
     724 * @brief Adds a dirty rectangle to 'base' according to a strategy.
     725 *
     726 * @param[in] list              the list to add to
     727 * @param[in] box               the dirty frame to addable
     728 * @param[in] strategy  the dirty frame heuristic to use (see gfx_options.h)
    635729 */
    636730void gfxdr_add_dirty(DirtyRectList &list, rect_t box, int strategy);
    637731
     732/**
     733 * @brief Clips a rectangle against another one.
     734 *
     735 * @param[in] rect              The rectangle to clip
     736 * @param[in] clipzone  The outer bounds rect must be in
     737 * @return                              1 if rect is empty now, 0 otherwise
     738 */
    638739int _gfxop_clip(rect_t *rect, rect_t clipzone);
    639 /* Clips a rectangle against another one
    640 ** Parameters: (rect_t *) rect: The rectangle to clip
    641 **             (rect_t) clipzone: The outer bounds rect must be in
    642 ** Reuturns  : (int) 1 if rect is empty now, 0 otherwise
    643 */
     740/** @} */
    644741
    645742} // End of namespace Sci
    646743
  • engines/sci/gfx/palette.h

    diff --git a/engines/sci/gfx/palette.h b/engines/sci/gfx/palette.h
    index 127871b..65d1cac 100644
    a b struct PaletteEntry {  
    4242                : r(R), g(G), b(B), parent_index(-1), refcount(PALENTRY_FREE)
    4343        { }
    4444
    45         // Color data
     45        /** @name Color data */
     46        /** @{ */
    4647        byte r, g, b;
     48        /** @} */
    4749
    48         // Index in parent palette, or -1
     50        /** Index in parent palette, or -1 */
    4951        int parent_index;
    5052
    51         // Number of references from child palettes. (This includes palettes
    52         // of pixmaps.)
    53         // Special values: PALENTRY_LOCKED, PALENTRY_FREE
     53        /**
     54         * Number of references from child palettes. (This includes palettes
     55         * of pixmaps.)
     56         * Special values: PALENTRY_LOCKED, PALENTRY_FREE */
    5457        int refcount;
    5558};
    5659
    private:  
    98101
    99102        Palette *_parent;
    100103
    101         bool _dirty; // Palette has changed
    102         int _refcount; // Number of pixmaps (or other objects) using this palette
    103         int _revision; // When this is incremented, all child references are
    104                        // invalidated
     104        bool _dirty; /**< Palette has changed */
     105        int _refcount; /**< Number of pixmaps (or other objects) using this palette */
     106        int _revision; /**< When this is incremented, all child references are invalidated */
    105107};
    106108
    107109
  • engines/sci/gfx/res_pic.cpp

    diff --git a/engines/sci/gfx/res_pic.cpp b/engines/sci/gfx/res_pic.cpp
    index 762cb7b..5ee2665 100644
    a b void gfxr_init_static_palette() {  
    152152}
    153153
    154154
    155 gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, int sci1) {
     155gfxr_pic_t *gfxr_init_pic(gfx_mode_t *mode, int ID, bool sci1) {
    156156        gfxr_pic_t *pic = (gfxr_pic_t*)malloc(sizeof(gfxr_pic_t));
    157157
    158158        pic->mode = mode;
  • engines/sci/gfx/seq_decoder.h

    diff --git a/engines/sci/gfx/seq_decoder.h b/engines/sci/gfx/seq_decoder.h
    index 1657400..dbadc46 100644
    a b  
    2828
    2929namespace Sci {
    3030
     31/**
     32 * @brief Decoder for image sequences
     33 */
    3134class SeqDecoder {
    3235public:
    3336        SeqDecoder() : _fileStream(0), _palette(0) { }
    public:  
    3740        gfx_pixmap_t *getFrame(bool &hasNext);
    3841
    3942private:
    40         bool decodeFrame(byte *runlength_data, int runlength_size, byte *literal_data, int literal_size, byte *dest, int xl, int yl, int color_key);
     43        bool decodeFrame(byte *runlength_data, int runlength_size,
     44                byte *literal_data, int literal_size, byte *dest, int xl, int yl,
     45                int color_key);
    4146
    4247        Common::SeekableReadStream *_fileStream;
    4348        Palette *_palette;