From db6b6d1f74bb2470155942822729e12c6f237174 Mon Sep 17 00:00:00 2001
From: Elias Batek <desisma@heidel.beer>
Date: Mon, 7 Oct 2024 03:24:22 +0200
Subject: [PATCH] Slightly improve docs and usability

---
 pixmappaint.d | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/pixmappaint.d b/pixmappaint.d
index 2e73cee..adff89c 100644
--- a/pixmappaint.d
+++ b/pixmappaint.d
@@ -343,10 +343,13 @@ struct Pixmap {
 	/++
 		Retrieves a rectangular subimage of the pixmap.
 	 +/
-	inout(SubPixmap) scan2D(Point pos, Size size) inout {
+	inout(SubPixmap) scanSubPixmap(Point pos, Size size) inout {
 		return inout(SubPixmap)(this, size, pos);
 	}
 
+	/// TODO: remove
+	deprecated alias scan2D = scanSubPixmap;
+
 	/++
 		Retrieves the first line of the Pixmap.
 
@@ -357,6 +360,42 @@ struct Pixmap {
 		return data[0 .. width];
 	}
 
+	public {
+		/++
+			Provides access to a single pixel at the requested 2D-position.
+
+			See_also:
+				Accessing pixels through the [data] array will be more useful,
+				usually.
+		 +/
+		ref inout(Pixel) accessPixel(Point pos) inout @system {
+			const idx = linearOffset(pos, this.width);
+			return this.data[idx];
+		}
+
+		/// ditto
+		Pixel getPixel(Point pos) const {
+			const idx = linearOffset(pos, this.width);
+			return this.data[idx];
+		}
+
+		/// ditto
+		Pixel getPixel(int x, int y) const {
+			return this.getPixel(Point(x, y));
+		}
+
+		/// ditto
+		void setPixel(Point pos, Pixel value) {
+			const idx = linearOffset(pos, this.width);
+			this.data[idx] = value;
+		}
+
+		/// ditto
+		void setPixel(int x, int y, Pixel value) {
+			return this.setPixel(Point(x, y), value);
+		}
+	}
+
 	/// Clears the buffer’s contents (by setting each pixel to the same color)
 	void clear(Pixel value) {
 		data[] = value;
@@ -1733,7 +1772,10 @@ Pixmap cropInPlace(Pixmap source, Size targetSize, Point offset = Point(0, 0)) @
 	$(PITFALL
 		This function does not work in place.
 		Do not attempt to pass Pixmaps sharing the same buffer for both source
-		and target. Such would lead to a bad result with heavy artifacts.
+		and target. Such would lead to bad results with heavy artifacts.
+
+		Do not use the artifacts produced by this as a creative effect.
+		Those are an implementation detail.
 	)
  +/
 void rotateClockwise(const Pixmap source, Pixmap target) @nogc {