1 files changed, 127 insertions, 0 deletions
diff --git a/chalk/doc/selections b/chalk/doc/selections
new file mode 100644
index 00000000..bdcdaa03
--- /dev/null
+++ b/chalk/doc/selections
@@ -0,0 +1,127 @@
+Selections in Chalk
+
+Please disregard any lingering presence of the KisFloatingSelection
+class and the associated rectangular marque rendering code. If you
+find anything connected with that after I finish coding the new
+selections scheme, it's something I forgot.
+
+Selections in Chalk are special paint devices as big as their tqparent
+layer. The selection has the alpha colour strategy. The alpha channel
+contains the selectedness of a pixel. It is not a binary value, but a scale,
+hardcoded to 8 bits unsigned
+
+TODO: * implement heterogenous compositing. (Needs knowledge by the
+        target layer of the color strategy of the source layer).
+
+Selections can be changed using tools that are clones of the usual
+painting tools: brush, eraser, polygon, etc. 
+
+TODO: * implement most of these, the polygon, circle, rectangle tools
+        should fill by default. XXX: make it easier to leverage the
+	code for the standard tools: after all, the only difference
+	is which layer they should paint on.
+
+XXX: Fill-by-default should be an option for the polygon, circle,
+     rectangle painting tools, too.
+
+Selections can also changed by procedures like select-by-color etc.
+
+TODO: * finish dialog for select by color
+      * implement select-by-color (depends on usable iterators)
+
+Selections are represented as 0== unselected and 255 == fully
+selected. Values in between are semi selected
+
+Other representations of selections are possible: the selection for a
+particular rect is rendered as a separate step in
+KisImage::renderToProjection. I like the tqmask type rendering, but
+someone else might want to provide an optional marque-rendering.
+
+TODO: * enable kconfig option to select between renderings.
+
+Selected pixels can be mangled -- for instance, filled with a
+gradient, moved, made brighter, lighter or sprightlier, cut and
+pasted. These manglings fall into two groups: the kind that demands
+that the selected pixels are removed from their native layer, and the
+kind that merely changes their value.
+
+
+A) Moving, cutting, copying, pasting.
+
+Each of these operations moves pixels to a new KisLayer that is not
+part of the regular stack of layers. The operations are defined as 
+follows:
+
+Moving: create new layer, copy selected pixels to this layer, set
+pixels in old layer to transparent background colour, set new layer
+visible.
+
+Cutting: create new layer, copy selected pixels to this layer, set
+pixels in old layer to transparent background colour, add new layer to
+the cut scrapbook (if we're going to have such a thing).
+
+XXX: Discuss desirability of cut scrapbook.
+
+Copying: create new layer, copy selected pixels to this layer, add new
+layer to the cut scrapbook (if we're going to have such a thing).
+
+Pasting: check if cut or copy layer exists in scrapbook, copy pixels
+from this layer to the target layer.
+
+B) Changing the value of selected pixels
+
+Use cases: fills (gradient, pattern, color), filtering.
+
+Fills are easiest implemented by creating a filled paint device for
+the rect covered by the selection, and then, while composting the fill
+with the target layer, pass the tqmask to the compositing loop, and skip
+un-selected pixels. 
+
+XXX: Discuss whether this is true
+
+Filtering needs looping over all pixels of a layer, and, if selection
+is present, only apply filter to the selected pixel.
+
+XXX: What about convolving, which takes a matrix of pixels. If only
+the middle pixel of a matrix is selected, should we take the input of
+the surrounding unselected pixels, or should the operation then assume
+edge conditions? Or should this be an option?
+
+TODO: infrastructure for all these operations, actual implementation.
+
+Actions to a selection need to be undoable. 
+
+TODO: Make it so.
+
+I am not sure whether selections need to be saved and loaded:
+Photoshop offers this, but our selection mechanism works differently.
+The Gimp offers selection adding/subtracting, but that's also not
+really necessary. A good idea is perhaps to add a combobox to the
+selection tool properties widget to choose between 'select' and
+'deselect', where the brush is initially set to 'select' and the
+eraser to 'deselect'.
+
+From a thread in the mailing list Boudewijn wrote:
+-----------------------------------------------------------------------
+This is the behaviour I expect from a paint app:
+
+If there's a selection on the current layer, only the selected pixels in the 
+current layer should be transformed, rotated, scaled or sheared. This happens 
+within the layer. If the new pixels overlap untransformed pixels, they are 
+composed with the giving composite op and opacity.
+
+If there's no selection, a transform on a layer should transform all pixels in 
+a layer, i.e., act as if the layer was completely selected. No new layer is 
+created. There is no composition, because the old layer data is completely 
+discarded.
+
+If a transform is applied to a image, all layers are transformed. The 
+selection is transformed, too: in the new situation, the layer that has a 
+selection active still has a selection, but the tqshape of the selection is 
+transformed.
+
+If a layer is moved, the selection moves with the layer (this is not 
+implemented yet).
+
+A transform never creates a new layer (expect perhaps temporarily and it 
+wouldn't be visible to the user).