Merge pull request #364 from lordhoto/sub-surface

GRAPHICS: Allow to query a Surface describing a subarea in Surface.

graphics/surface.cpp

@@ -97,6 +97,34 @@ void Surface::copyFrom(const Surface &surf) {
 	}
 }
 
+Surface Surface::getSubArea(const Common::Rect &area) {
+	Common::Rect effectiveArea(area);
+	effectiveArea.clip(w, h);
+
+	Surface subSurface;
+	subSurface.w = effectiveArea.width();
+	subSurface.h = effectiveArea.height();
+	subSurface.pitch = pitch;
+	subSurface.pixels = getBasePtr(area.left, area.top);
+	subSurface.format = format;
+	return subSurface;
+}
+
+const Surface Surface::getSubArea(const Common::Rect &area) const {
+	Common::Rect effectiveArea(area);
+	effectiveArea.clip(w, h);
+
+	Surface subSurface;
+	subSurface.w = effectiveArea.width();
+	subSurface.h = effectiveArea.height();
+	subSurface.pitch = pitch;
+	// We need to cast the const away here because a Surface always has a
+	// pointer to modifiable pixel data.
+	subSurface.pixels = const_cast<void *>(getBasePtr(area.left, area.top));
+	subSurface.format = format;
+	return subSurface;
+}
+
 void Surface::hLine(int x, int y, int x2, uint32 color) {
 	// Clipping
 	if (y < 0 || y >= h)

graphics/surface.h

@@ -134,11 +134,43 @@ struct Surface {
 	 */
 	void copyFrom(const Surface &surf);
 
+	/**
+	 * Creates a Surface which represents a sub-area of this Surface object.
+	 *
+	 * The pixel (0, 0) of the returned Surface will be the same as Pixel
+	 * (area.x, area.y) of this Surface. Changes to any of the Surface objects
+	 * will change the shared pixel data.
+	 *
+	 * Note that the Surface returned is only valid as long as this Surface
+	 * object is still alive (i.e. its pixel data is not destroyed or
+	 * reallocated). Do *never* try to free the returned Surface.
+	 *
+	 * @param area The area which should be represented. Note that the area
+	 *             will get clipped in case it does not fit!
+	 */
+	Surface getSubArea(const Common::Rect &area);
+
+	/**
+	 * Creates a Surface which represents a sub-area of this Surface object.
+	 *
+	 * The pixel (0, 0) of the returned Surface will be the same as Pixel
+	 * (area.x, area.y) of this Surface.
+	 *
+	 * Note that the Surface returned is only valid as long as this Surface
+	 * object is still alive (i.e. its pixel data is not destroyed or
+	 * reallocated). Do *never* try to free the returned Surface.
+	 *
+	 * @param area The area which should be represented. Note that the area
+	 *             will get clipped in case it does not fit!
+	 */
+	const Surface getSubArea(const Common::Rect &area) const;
+
 	/**
 	 * Convert the data to another pixel format.
 	 *
 	 * This works in-place. This means it will not create an additional buffer
-	 * for the conversion process. The value of pixels might change though.
+	 * for the conversion process. The value of 'pixels' might change though
+	 * (that means it might realloc the pixel data).
 	 *
 	 * Note that you should only use this, when you created the Surface data via
 	 * create! Otherwise this function has undefined behavior.