1 files changed, 54 insertions, 0 deletions
diff --git a/chalk/doc/autoextending paintdevices b/chalk/doc/autoextending paintdevices
new file mode 100644
index 00000000..a42dc683
--- /dev/null
+++ b/chalk/doc/autoextending paintdevices
@@ -0,0 +1,54 @@
+ 
+This is an attempt to explain how autosizing paintdevices work
+
+The tileddatamanager which is the underlying object that organizes the pixel
+storage is autoextending. So it starts with zero tiles, and as writing is
+being done new tiles are added as needed.
+
+There is also a default tile that is only readable (in theory). Whenever
+access is only readaccess you get this tile for areas that don't have their
+own tile yet. The idea is that the default tile is filled with transparent
+pixels. (Or, with special layers like the background pattern or the selection,
+with something else relevant. bsar)
+
+
+So imagine a new image of size 640x640. The layer has no tiles, but when the
+layer is being read (for viewing) we probe all over the image (640x640) and
+read from the default tile wherever we probe.
+
+The extent of the layer (paintdevice) is 0x0 because nothing has been
+written yet.
+
+Then some drawing is done in one corner and a tile is created automatically.
+Now the extent is 64x64 (tilesize defined at compilation) because a single
+tile exists.
+
+If some drawing is done in the opposite corner another tile is created. The
+extent is now 640x640, but only two tiles exist (one in each opposite
+corner). When probing for viewing the default tile is what you get except
+for the two tiles.
+
+If we now apply a filer that lightens the colors (or something else) we
+could iterate over the extent. That way we are sure to get all the real
+tiles that have been created.
+
+As there is no way for us to know which pixel have true tiles and which have
+the default, we would write to all the pixels within the extent, which would
+automatically create ALL the tiles inside the extent.
+(XXX: Of course, the tile manager could decide that the written value
+is the same as the default value, and if that's true for all pixels in a tile, 
+not create a tile at all) (bsar))
+
+In other cases like a gradient fill we would probably want to fill the
+current image area, so we we would just write to the paintdevice, and tiles
+would be automatically created for us.
+
+So in short: if you read - data will be available (either real tiles or a
+default) - and if you write to the paintdevice - tiles will be created as
+needed. So simply don't worry.
+
+But in some cases, when you want to modify already written pixels, as in
+some filters you want to know where true data have been written. Otherwise
+we would have to modify an infinite number of pixels to be sure everything is
+changed. This is where the extent comes in handy. If you have absolutely 
+no leeway, use exactBounds which is slow, but sure.