diff options
Diffstat (limited to 'graphics')
| -rw-r--r-- | graphics/surface.h | 123 |
1 files changed, 114 insertions, 9 deletions
diff --git a/graphics/surface.h b/graphics/surface.h index 20ab816236..f9cb6cc474 100644 --- a/graphics/surface.h +++ b/graphics/surface.h @@ -35,55 +35,160 @@ namespace Graphics { * operations, font rendering, etc. */ struct Surface { + /* + * IMPORTANT implementation specific detail: + * + * ARM code relies on the layout of the first 3 of these fields. Do not + * change them. + */ + /** - * ARM code relies on the layout of the first 3 of these fields. Do - * not change them. + * The width of the surface. */ uint16 w; + + /** + * The height of the surface. + */ uint16 h; + + /** + * The number of bytes a pixel line has. + * + * Note that this might not equal w * bytesPerPixel. + */ uint16 pitch; + + /** + * The surface's pixel data. + */ void *pixels; + + /** + * How many bytes a single pixel occupies. + */ uint8 bytesPerPixel; - Surface() : w(0), h(0), pitch(0), pixels(0), bytesPerPixel(0) {} + /** + * Construct a simple Surface object. + */ + Surface() : w(0), h(0), pitch(0), pixels(0), bytesPerPixel(0) { + } + + /** + * Return a pointer to the pixel at the specified point. + * + * @param x The x coordinate of the pixel. + * @param y The y coordinate of the pixel. + * @return Pointer to the pixel. + */ inline const void *getBasePtr(int x, int y) const { return (const byte *)(pixels) + y * pitch + x * bytesPerPixel; } + /** + * Return a pointer to the pixel at the specified point. + * + * @param x The x coordinate of the pixel. + * @param y The y coordinate of the pixel. + * @return Pointer to the pixel. + */ inline void *getBasePtr(int x, int y) { return static_cast<byte *>(pixels) + y * pitch + x * bytesPerPixel; } /** - * Allocate pixels memory for this surface and for the specified dimension. + * Allocate memory for the pixel data of the surface. + * + * Note that you are responsible for calling free yourself. + * @see free + * + * @param width Width of the surface object. + * @param height Height of the surface object. + * @param bytePP The number of bytes a single pixel uses. */ void create(uint16 width, uint16 height, uint8 bytesPP); /** * Release the memory used by the pixels memory of this surface. This is the * counterpart to create(). + * + * Note that you should only use this, when you created the Surface data via + * create! Otherwise this function has undefined behavior. + * @see create */ void free(); /** - * Copies data from another Surface, this calls *free* on the current surface, to assure - * it being clean. + * Copy the data from another Surface. + * + * Note that this calls free on the current surface, to assure it being + * clean. So be sure the current data was created via create, otherwise + * the results are undefined. + * @see create + * @see free + * + * @param surf Surface to copy from. */ void copyFrom(const Surface &surf); + /** + * Draw a line. + * + * @param x0 The x coordinate of the start point. + * @param y0 The y coordiante of the start point. + * @param x1 The x coordinate of the end point. + * @param y1 The y coordinate of the end point. + * @param color The color of the line. + */ void drawLine(int x0, int y0, int x1, int y1, uint32 color); + + /** + * Draw a horizontal line. + * + * @param x The start x coordinate of the line. + * @param y The y coordiante of the line. + * @param x2 The end x coordinate of the line. + * In case x > x2 the coordinates are swapped. + * @param color The color of the line. + */ void hLine(int x, int y, int x2, uint32 color); + + /** + * Draw a vertical line. + * + * @param x The x coordinate of the line. + * @param y The start y coordiante of the line. + * @param y2 The end y coordinate of the line. + * In case y > y2 the coordinates are swapped. + * @param color The color of the line. + */ void vLine(int x, int y, int y2, uint32 color); + + /** + * Fill a rect with a given color. + * + * @param r Rect to fill + * @param color The color of the rect's contents. + */ void fillRect(Common::Rect r, uint32 color); + + /** + * Draw a frame around a specified rect. + * + * @param r Rect to frame + * @param color The color of the frame. + */ void frameRect(const Common::Rect &r, uint32 color); + // See comment in graphics/surface.cpp about it void move(int dx, int dy, int height); }; /** - * For safe deletion of surface with SharedPtr. - * The deleter assures Surface::free is called on - * deletion. + * A deleter for Surface objects which can be used with SharedPtr. + * + * This deleter assures Surface::free is called on deletion. */ struct SharedPtrSurfaceDeleter { void operator()(Surface *ptr) { |