koffice/chalk/doc/selections

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).