/* ScummVM - Graphic Adventure Engine * * ScummVM is the legal property of its developers, whose names * are too numerous to list here. Please refer to the COPYRIGHT * file distributed with this source distribution. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * * $URL$ * $Id$ * */ #ifndef _SCI_GFX_DRIVER_H_ #define _SCI_GFX_DRIVER_H_ #include "sci/include/gfx_system.h" #include "sci/include/uinput.h" typedef enum { GFX_BUFFER_FRONT = 0, GFX_BUFFER_BACK = 1, GFX_BUFFER_STATIC = 2 } gfx_buffer_t; /* graphics driver hints */ #define GFX_CAPABILITY_SHADING (1<<0) #define GFX_CAPABILITY_MOUSE_POINTER (1<<1) #define GFX_CAPABILITY_COLOR_MOUSE_POINTER (1<<2) #define GFX_CAPABILITY_PIXMAP_REGISTRY (1<<3) #define GFX_CAPABILITY_SCALEABLE_PIXMAPS (1<<4) #define GFX_CAPABILITY_STIPPLED_LINES (1<<6) #define GFX_CAPABILITY_MOUSE_SUPPORT (1<<7) #define GFX_CAPABILITY_POINTER_PIXMAP_REGISTRY (1<<8) #define GFX_CAPABILITY_FINE_LINES (1<<9) #define GFX_CAPABILITY_WINDOWED (1<<10) #define GFX_CAPABILITY_KEYTRANSLATE (1<<11) #define GFX_DEBUG_POINTER (1<<0) #define GFX_DEBUG_UPDATES (1<<1) #define GFX_DEBUG_PIXMAPS (1<<2) #define GFX_DEBUG_BASIC (1<<3) /* Basic geometric ops (lines, boxes, etc) */ /* Principial graphics driver architecture ** --------------------------------------- ** ** All graphics drivers must provide ** - One visual front buffer (the actually visible thing) ** - Two dynamic back buffers: ** + visual ** + priority ** - Two static buffers (containing the background image and picviews): ** + visual ** + priority ** ** The control buffer is handled outside the graphics driver architecture. ** Graphics are drawn by first setting the static buffers, then updating ** the back buffers (from the static buffers), adding all picviews and other ** widgets, and finally updating the front buffer. ** ** All coordinates refer to the scaled coordinate system. ** Invalid parameters should produce an error message. ** Support for some valid parameter values is optional (like different line ** modes). If an unsupported but valid parameter is specified, the function ** must use a reasonable default value. */ #define SCI_GFX_DRIVER_VERSION 0 #define SCI_GFX_DRIVER_MAGIC 0xf001337 typedef struct _gfx_driver { /* Graphics driver */ const char *name; /* Graphics driver name. Unique identifier, should consist of ** lower-case (where applicable) alphanumerics */ const char *version; /* Free-form version description (for informative purposes ** only) */ int sci_driver_magic; /* SCI_GFX_DRIVER_MAGIC */ int sci_driver_version; /* SCI_GFX_DRIVER_VERSION */ gfx_mode_t *mode; /* Currently active mode, NULL if no mode is active */ int pointer_x, pointer_y; /* Mouse pointer position */ int capabilities; /* The driver's capabilities: A list of flags that may ** be pre-defined or set after a successful initialization. */ /* Capability flags: ** ** The words MUST, SHOULD and MAY are to be interpreted as described in ** the IETF RFC 1123. ** ** GFX_CAPABILITY_SHADING: draw_filled_rect() supports drawing shaded ** rectangles. ** GFX_CAPABILITY_MOUSE_POINTER: The driver has built-in support for mouse ** pointers (monochrome or colored). ** GFX_CAPABILITY_COLOR_MOUSE_POINTER: The driver has built-in support for ** colored mouse pointers. ** GFX_CAPABILITY_PIXMAP_REGISTRY: System provides a pixmap registry. The ** invoking functions will assume that all pixmaps MUST be registered; ** if this flag is not set, it assumes that pixmaps MUST NOT be ** registered. Note that this excludes pointer pixmaps (see below) ** GFX_CAPABILITY_POINTER_PIXMAP_REGISTRY: The system provides a pixmap ** registry which mouse pointers have to be registered in explicitly. ** This MUST be used only if the registry is identical to the 'normal' pixmap ** registry. Otherwise, it MUST be handled manually by the driver, ** unless pointer support is disabled completely. ** GFX_CAPABILITY_SCALEABLE_PIXMAPS: Pixmap scaling is fully supported. ** If this capability is flag is set, all pixmaps passed to the driver ** will be unscaled. ** GFX_CAPABILITY_STIPPLED_LINES: The driver is able to draw stippled lines ** horizontally and vertically (xl = 0 or yl = 0). ** GFX_CAPABILITY_MOUSE_SUPPORT: There is some support for mouse (or similar) ** input. Note that this flag may be disabled by external code after ** initialization time, if no support for mouse pointer /drawing/ is ** available. ** GFX_CAPABILITY_FINE_LINES: Should be set IFF the driver supports drawing ** fine (width 1) lines ** GFX_CAPABILITY_WINDOWED: Driver runs in a window and supports a debug ** console running on stdin/stdout ** GFX_CAPABILITY_KEYTRANSLATE: The driver's input layer automatically ** handles 'shifted' keys (i.e. turning shift-'a' to 'A' etc.). ** Drivers only need to handle this if they desire to support ** non-US keyboard layouts, usually by localisation methods ** provided by the underlying windowing or operating system. */ unsigned int debug_flags; /* Driver debug flags */ /*** Initialization ***/ int (*set_parameter)(struct _gfx_driver *drv, char *attribute, char *value); /* Sets a driver-specific parameter ** Parameters: (gfx_driver_t *) drv: Pointer to the affected driver ** (char *) attribute: Name of the attribute/parameter to set ** (char *) value: The value to set, or NULL to query the value ** Returns : (int) GFX_OK or GFX_FATAL, which signals a fatal error ** condition. ** This function should make extensive use of sciprintf() to signal invalid ** values or unapplicable attributes. ** Note that it may be called either before initialization (to interpret ** config file or command line parameters) or afterwars (from the command ** console). */ int (*init_specific)(struct _gfx_driver *drv, int xres, int yres, int bytespp); /* Attempts to initialize a specific graphics mode ** Parameters: (gfx_driver_t *) drv: The affected driver ** (int x int) xres, yres: Horizontal and vertical scaling ** factors ** (int) bytespp: Any of GFX_COLOR_MODE_*. GFX_COLOR_MODE_INDEX ** implies color index mode. ** Returns : (int) GFX_OK on success, GFX_ERROR if the mode could not be ** set, or GFX_FATAL if the graphics target is unuseable. ** The scaling factors apply to the standard SCI resolution of 320x200 pixels ** and is used for internal representation of graphical data. The physical ** resolution set by the graphics driver may be different for practical ** reasons. ** Must also set drv->mode, preferably with the gfx_new_mode() function ** specified in gfx_tools.h. */ int (*init)(struct _gfx_driver *drv); /* Initialize any graphics mode ** Parameters: (gfx_driver_t *) drv: The affected driver ** Returns : (int) GFX_OK on success, GFX_FATAL otherwise. ** This function attempts to set /any/ graphics mode, starting with the one ** most 'natural' to the graphics target. Target implementors have relatively ** free reign in choosing the heuristics used to determine the resulting ** mode. ** Must also set drv->mode, preferably with the gfx_new_mode() function ** specified in gfx_tools.h. */ void (*exit)(struct _gfx_driver *drv); /* Uninitializes the current graphics mode ** Paramters: (gfx_driver_t *) drv: The driver to uninitialize ** Return : (void) ** This function frees all memory allocated by the graphics driver, ** including mode and palette information, uninstalls all console commands ** introduced by preceeding init() or init_specific() commands, and does any ** clean-up work (like closing visuals or returning to text mode) required by ** the graphics infrastructure used. */ /*** Drawing operations ***/ int (*draw_line)(struct _gfx_driver *drv, point_t start, point_t end, gfx_color_t color, gfx_line_mode_t line_mode, gfx_line_style_t line_style); /* Draws a single line to the back buffer. ** Parameters: (gfx_driver_t *) drv: The driver affected ** (point_t) start: Starting point of the line to draw ** (point_t) end: End point of the line to draw ** (gfx_color_t *) color: The color to draw with ** (int) line_mode: Any of the line modes ** (int) line_style: Any of the line styles ** Returns : (int) GFX_OK or GFX_FATAL ** Note that color.priority is relevant and must be drawn if ** (color.mask & GFX_MASK_PRIORITY). ** Support for line modes other than GFX_LINE_MODE_FAST is optional. ** For non-fine lines, the coordinates provided describe the upper left ** corner of the pixels of the line to draw. ** line_style support is optional, if GFX_CAPABILITY_STIPPLED_LINES is not ** set. */ int (*draw_filled_rect)(struct _gfx_driver *drv, rect_t rect, gfx_color_t color1, gfx_color_t color2, gfx_rectangle_fill_t shade_mode); /* Draws a single filled and possibly shaded rectangle to the back buffer. ** Parameters: (gfx_driver_t *) drv: The driver affected ** (rect_t *) rect: The rectangle to draw ** (gfx_color_t *) color1, color2: The colors to draw with ** (int) shade_mode: Any of GFX_SHADE_*. ** Returns : (int) GFX_OK or GFX_FATAL ** Note that color.priority is relevant and must be drawn if ** (color.mask & GFX_MASK_PRIORITY). ** color2 is relevant only if shade_mode is not GFX_SHADE_FLAT. ** Support for shade modes other than GFX_SHADE_FLAT is optional. */ /*** Pixmap operations ***/ int (*register_pixmap)(struct _gfx_driver *drv, gfx_pixmap_t *pxm); /* Registers a pixmap with the driver. ** Parameters: (gfx_driver_t *) drv: The driver ** (gfx_pixmap_t *) pxm: The pixmap to register ** Returns : GFX_OK or GFX_FATAL ** This function may be NULL if GFX_CAPABILITY_PIXMAP_REGISTRY is not ** set. ** pxm->internal may be used to store any handle or meta information. */ int (*unregister_pixmap)(struct _gfx_driver *drv, gfx_pixmap_t *pxm); /* Unregisters a pixmap previously registered with register_pixmap() ** Parameters: (gfx_driver_t *) drv: The driver ** (gfx_pixmap_t *) pxm: The pixmap to register ** Returns : (int) GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was ** not registered ** Just like register_pixmap(), this function may be NULL unless ** GFX_CAPABILITY_PIXMAP_REGISTRY is set. */ int (*draw_pixmap)(struct _gfx_driver *drv, gfx_pixmap_t *pxm, int priority, rect_t src, rect_t dest, gfx_buffer_t buffer); /* Draws part of a pixmap to the static or back buffer ** Parameters: (gfx_driver_t *) drv: The affected driver ** (gfx_pixmap_t *) pxm: The pixmap to draw ** (int) priority: The priority to draw with, or GFX_NO_PRIORITY ** to draw on top of everything without setting the ** priority back buffer ** (rect_t) src: The pixmap-relative source rectangle ** (rect_t) dest: The destination rectangle ** (int) buffer: One of GFX_BUFFER_STATIC and GFX_BUFFER_BACK ** Returns : (int) GFX_OK or GFX_FATAL, or GFX_ERROR if pxm was not ** (but should have been) registered. ** dest.xl and dest.yl must be evaluated and used for scaling if ** GFX_CAPABILITY_SCALEABLE_PIXMAPS is supported. */ int (*grab_pixmap)(struct _gfx_driver *drv, rect_t src, gfx_pixmap_t *pxm, gfx_map_mask_t map); /* Grabs an image from the visual or priority back buffer ** Parameters: (gfx_driver_t *) drv: The affected driver ** (rect_t) src: The rectangle to grab ** (gfx_pixmap_t *) pxm: The pixmap structure the data is to ** be written to ** (int) map: GFX_MASK_VISUAL or GFX_MASK_PRIORITY ** Returns : (int) GFX_OK, GFX_FATAL, or GFX_ERROR for invalid map values ** pxm may be assumed to be empty and pre-allocated with an appropriate ** memory size. ** This function is now mandatory. */ /*** Buffer operations ***/ int (*update)(struct _gfx_driver *drv, rect_t src, point_t dest, gfx_buffer_t buffer); /* Updates the front buffer or the back buffers ** Parameters: (gfx_driver_t *) drv: The affected driver ** (rect_t) src: Source rectangle ** (point_t) dest: Destination point ** (int) buffer: One of GFX_BUFFER_FRONT or GFX_BUFFER_BACK ** Returns : (int) GFX_OK, GFX_ERROR or GFX_FATAL ** This function updates either the visual front buffer, or the two back ** buffers, by copying the specified source region to the destination ** region. ** For heuristical reasons, it may be assumed that the x and y fields of ** src and dest will be identical in /most/ cases. ** If they aren't, the priority map will not be required to be copied. */ int (*set_static_buffer)(struct _gfx_driver *drv, gfx_pixmap_t *pic, gfx_pixmap_t *priority); /* Sets the contents of the static visual and priority buffers ** Parameters: (gfx_driver_t *) drv: The affected driver ** (gfx_pixmap_t *) pic: The image defining the new content ** of the visual back buffer ** (gfx_pixmap_t *) priority: The priority map containing ** the new content of the priority back buffer ** in the index buffer ** Returns : (int) GFX_OK or GFX_FATAL ** pic and priority may be modified or written to freely. They may also be ** used as the actual static buffers, since they are not freed and re- ** allocated between calls to set_static_buffer() and update(), unless ** exit() was called in between. ** Note that later version of the driver interface may disallow modifying ** pic and priority. ** pic and priority are always scaled to the appropriate resolution, even ** if GFX_CAPABILITY_SCALEABLE_PIXMAPS is set. */ /*** Mouse pointer operations ***/ int (*set_pointer)(struct _gfx_driver *drv, gfx_pixmap_t *pointer); /* Sets a new mouse pointer. ** Parameters: (gfx_driver_t *) drv: The driver to modify ** (gfx_pixmap_t *) pointer: The pointer to set, or NULL to set ** no pointer ** Returns : (int) GFX_OK or GFX_FATAL ** This function may be NULL if GFX_CAPABILITY_MOUSE_POINTER is not set. ** If pointer is not NULL, it will have been scaled to the appropriate ** size and registered as a pixmap (if neccessary) beforehand. ** If this function is called for a target that supports only two-color ** pointers, the image is a color index image, where only color index values ** 0, 1, and GFX_COLOR_INDEX_TRANSPARENT are used. */ /*** Palette operations ***/ int (*set_palette)(struct _gfx_driver *drv, int index, byte red, byte green, byte blue); /* Manipulates a palette index in the hardware palette ** Parameters: (gfx_driver_t *) drv: The driver affected ** (int) index: The index of the palette entry to modify ** (int x int x int) red, green, blue: The RGB intensities to ** set for the specified index. The minimum ** intensity is 0, maximum is 0xff. ** Returns : (int) GFX_OK, GFX_ERROR or GFX_FATAL ** This function does not need to update mode->palette, as this is done ** by the calling code. ** set_palette() is only required for targets supporting color index mode. */ /*** Event management ***/ sci_event_t (*get_event)(struct _gfx_driver *drv); /* Returns the next event in the event queue for this driver ** Parameters: (gfx_driver_t *) drv: The driver to query ** Returns : (sci_event_t) The oldest event still in the driver's event ** queue, or the null event if there is none. */ int (*usec_sleep)(struct _gfx_driver *drv, long usecs); /* Sleeps the specified amount of microseconds, or until the mouse moves ** Parameters: (gfx_driver_t *) drv: The relevant driver ** (long) usecs: Amount of microseconds to sleep ** Returns : (int) GFX_OK or GFX_FATAL ** This function returns when the specified amount of microseconds has ** elapsed, or when the mouse pointer has been moved and needs to be redrawn. ** Only targets that can handle colored mouse pointers may choose to handle ** all mouse management internally. */ void *state; /* Reserved for internal use */ } gfx_driver_t; #endif /* !_SCI_GFX_DRIVER_H_ */