Finish rebranding of Krita as Chalk

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/koffice@1238363 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 620 insertions, 0 deletions

diff --git a/doc/chalk/using-layers.docbook b/doc/chalk/using-layers.docbook
new file mode 100644
index 00000000..3ca80291
--- /dev/null
+++ b/doc/chalk/using-layers.docbook
@@ -0,0 +1,620 @@
+<chapter id="layers">
+<title>Layers</title>
+
+<para>
+This chapter gives an overview of how layers work in &chalk;.
+</para>
+
+<sect1 id="layers-background">
+<title>Background information on layers</title>
+
+<para>
+Extensive use of &chalk; will almost require you to have some knowledge of
+layers. Using layers, you can work on one part of the image without touching
+the rest of it, and most effects are best applied on a layer, instead of on
+the whole image. Of course, if you do want to apply an effect to an entire
+image, &chalk; does offer you that possibility, and there is nothing against
+it.
+</para><para>
+The idea behind layers is quite simple. As the name suggests, layers lie on
+top of each other, and together form the layer stack. The final resulting
+image is that what you see when looking through the stack from top to bottom.
+This means that usually the upper layers of your image will have more or less
+transparency, since you cannot look through a layer which has no transparency.
+(&chalk; works with opaqueness instead of transparency. A layer that is 100
+percent opaque is 0 percent transparent, and vice versa.) A layer higher in
+the stack gets applied later than one lower in the stack. For example, if your
+image contains four layers, numbered from 1 (lowest) to 4 (highest), the
+effect that layer number 4 adds to the image, is applied to the result from
+applying layers 1 through 3.
+</para><para>
+Every image you edit in &chalk; contains layers. When you create a new image,
+the layer box (usually shown at the bottom right of your screen, see <link
+linkend="commands-palettes-layers-layers">this section</link>) will contain
+one layer. The painting and editing you do is then applied to that layer. Once
+you add more layers, you can choose on which part of the image you want to
+work, by selecting the respective layer. All further painting is then applied
+to that layer, until you select another one.
+</para><para>
+Layers are also an excellent way to check whether adding certain effects (or
+applying certain image modifications) come out right. Add a layer which
+contains what you want to try out, and show or hide it with the eye icon in
+the layer box. You can especially profit from this method if you have multiple
+effects to check out: show and hide them in any combination, and decide which
+you like best. And since you can move the layers around, you can also
+experiment with the order in which the effects are applied.
+</para><para>
+See the <link linkend="tutorial-select-layer">Selections and layers
+tutorial</link> for a small hands-on introduction.
+</para>
+</sect1>
+
+<sect1 id="layers-layerbox">
+<title>The layer box</title>
+
+<para>The layer box is the instrument you will use most to work with layers. It
+gives an overview of the layers that are present in your image, and using it
+you can manage layers by adding, removing, reordering or modifying them.
+</para><para>
+The layer box consists of three parts. The middle part gives an overview of the
+layers in the image. At the top, you can set some properties for the current
+layer. At the bottom, a couple of layer management options can be found. The
+next sections describe these three parts in more detail.
+</para>
+
+<sect2 id="layers-layerbox-overview"> 
+<title>Layer overview</title>
+
+<para>This part shows you which layers are present in your image. In a tree-like
+structure, the layer group hierarchy is shown: layers that are contained within
+a layer group are displayed a bit to the right to indicate their belonging to
+that group. 
+</para><para>
+For each layer, a thumbnail preview and its name are shown. The layer name
+is preceded by a folder icon if it is a group layer. Furthermore, two
+indicators are present: the eye icon shows whether the layer is currently
+visible (an open eye indicates that the layer is visible, a closed eye
+indicates that it is not), and the lock icon shows whether the layer is
+locked. No changes can be made to a locked layer.
+</para><para>
+When you click on a layer's eye icon, its visibility is switched from on to
+off or vice versa. Clicking on the lock icon enables or disables editing of
+that layer. You can click on the name of the current layer to rename it.
+Note that to rename a layer, it has to be the current one. You do not need to
+activate a layer in order to make it (in)visible or (un)locked via the eye and
+lock icons, respectively: these work directly.
+</para><para>
+Doubleclick on a layer entry in the list to open the <link
+linkend="commands-dialogs-layers-layerproperties"><guilabel>Layer
+Properties</guilabel></link> dialog. This dialog shows a layer's colorspace and
+profile. You can also change its name, opacity and composite mode here.
+</para>
+</sect2>
+
+<sect2 id="layers-layerbox-options"> 
+<title>Layer options</title>
+<para>
+The top of the layer box contains two controls for setting properties of the
+currently selected layer. The list box at the left allows you to quickly set
+the layer's composite mode. The spin field and slider at the right can be used
+to change the layer's opacity.
+</para><para>
+At the bottom of the layer box, there are five buttons. From left to right,
+these are as follows. The <guibutton>New Layer</guibutton> icon brings up a
+submenu from which you can choose which type of layer you want to add. This
+menu can also be opened by clicking with the &RMB; on the layer box. The
+<guibutton>Move Layer Down</guibutton> and <guibutton>Move Layer Up</guibutton>
+buttons move the current layer one level down and up, respectively, within the
+current layer group. If the layer is already the last or first within the
+layer group, trying to move it further will move it out of the layer group.
+The <guibutton>Layer Properties</guibutton> button opens the <link
+linkend="commands-dialogs-layers-layerproperties"><guilabel>Layer
+Properties</guilabel></link> dialog, just as when you would have doubleclicked
+on the layer. The <guibutton>Delete Layer</guibutton> button deletes the
+current layer.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="layers-working">
+<title>Working with layers</title>
+
+<para>
+Because layers are quite important when extensively using &chalk;, you can
+perform a lot of operations on them. These are all available via the <link
+linkend="commands-menus-layer"><guimenu>Layer</guimenu> menu</link>. Some of
+the possibilities:
+</para>
+
+<variablelist>
+<varlistentry><term></term><listitem><para>Add, remove, and duplicate layers;</para></listitem></varlistentry>
+<varlistentry><term></term><listitem><para>Create and edit layer masks;</para></listitem></varlistentry>
+<varlistentry><term></term><listitem><para>Flip, rotate, scale and shear layers;</para></listitem></varlistentry>
+<varlistentry><term></term><listitem><para>Convert layers between colorspaces;</para></listitem></varlistentry>
+<varlistentry><term></term><listitem><para>Save layers as images;</para></listitem></varlistentry>
+<varlistentry><term></term><listitem><para>View layer histograms.</para></listitem></varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="layers-adjustment">
+<title>Adjustment Layers</title>
+
+<para>Adjustment layers are layers that consist of a filter and an optional
+selection. The filter effect is applied to the composite image of all
+layers under the adjustment layer in the current layer group. The big
+thing is, adjustment layers apply these effects non-destructively. The
+original image data is not modified.
+</para><para>
+Almost all &chalk; filters are suitable for use in adjustment
+layers -- even filters that would downgrade the image quality. For instance,
+the raindrops filter converts to 8-bit RGB before working its magic. If you
+would try to use this filter directly on a 16-bit L*a*b* layer, &chalk; would
+warn you about the conversion to RGB and back again this filter would cause.
+Not so with adjustment layers: the original data isn't touched, so applying
+the filter is safe.
+</para><para>
+What about the colorspace of an adjustment layer then? In order to examine
+this issue, you need to know what happens when &chalk; renders an adjustment
+layer.
+</para>
+
+<sect2 id="layers-adjustment-selections">
+<title>Adjustment layers and selections</title>
+
+<para>If the currently active layer has an active selection, then that selection
+will be copied and used as a mask for the adjustment layer. If there is no
+active selection, then there will be no mask and the adjustment will apply to
+the entire extent of the layers under the adjustment layer in the current
+group. There is <emphasis>no</emphasis> way of adding a mask to an existing
+adjustment layer.
+</para><para>
+If there is a mask in the adjustment layer, you can edit the mask using the
+ordinary painting tools and painting operations.
+</para>
+
+</sect2>
+
+<sect2 id="layers-adjustment-projection">
+<title>A note on projections</title>
+
+<para>
+&chalk; composites the layers bottom to top, within each layer group. The
+aggregate -- or the projection as it is also called -- is then filtered by
+the adjustment layer. If there are layers on top of the adjustment layer,
+those are composited onto the projection. &chalk; converts all layer data before
+compositing, so if the bottom-most layer in an image is grayscale, all layers
+are converted to grayscale before compositing -- and that means that the
+adjustment layer projection will be grayscale, too.
+</para><para>
+With this knowledge you'll understand why &chalk; can often offer better
+performance working with layers on top of an adjustment layer which is on top
+of a complex layer structure: &chalk; uses the projection and doesn't even look
+anymore at the layers under the adjustment layer. Unless, of course, you
+change one of them.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="layers-composite">
+<title>Compositing modes</title>
+
+<para>
+Layers can be composited in various ways, each yielding a different effect.
+This section describes the available compositing modes. Each description is
+accompanied by an example: on top of an original image (see below), a rainbow
+gradient is added.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The original image</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-original.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The original image</phrase>
+</textobject>
+<caption><para>The original image</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<sect2 id="layers-composite-normal">
+<title><guilabel>Normal</guilabel></title>
+
+<para>
+The <guilabel>Normal</guilabel> mode does nothing special. It adds the layer
+to the image, and if no other special effects like opacity are changed, the
+underlying layers will only be visible at places where the new layer is
+itself transparent.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Normal</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-normal.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Normal</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Normal</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-multiply">
+<title><guilabel>Multiply</guilabel></title>
+
+<para>
+The <guilabel>Multiply</guilabel> mode blends the two layers so that the
+bottom layer gets <quote>colorized</quote> by the new layer. The resulting
+image is generally quite dark.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Multiply</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-multiply.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Multiply</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Multiply</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-burn">
+<title><guilabel>Burn</guilabel>, <guilabel>Dodge</guilabel>,
+<guilabel>Divide</guilabel> and <guilabel>Screen</guilabel></title>
+
+<para>
+The <guilabel>Burn</guilabel>, <guilabel>Dodge</guilabel>,
+<guilabel>Divide</guilabel> and <guilabel>Screen</guilabel> modes all add an
+extra <quote>burning</quote> effect by following contours instead of using
+straight lines. In addition, <guilabel>Burn</guilabel> and
+<guilabel>Divide</guilabel> use the inverted colors instead of the actual
+colors of the composited layer.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Burn</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-burn.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Burn</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Burn</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Dodge</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-dodge.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Dodge</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Dodge</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Divide</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-divide.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Divide</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Divide</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Screen</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-screen.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Screen</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Screen</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-overlay">
+<title><guilabel>Overlay</guilabel></title>
+
+<para>
+Like <guilabel>Multiply</guilabel>, the <guilabel>Overlay</guilabel> mode
+colorizes the underlying layer. The resulting image is about as light as
+the original layer.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Overlay</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-overlay.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Overlay</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Overlay</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-darken">
+<title><guilabel>Darken</guilabel></title>
+
+<para>
+The <guilabel>Darken</guilabel> mode darkens the underlying layer while
+colorizing it to match the colors in the composited layer.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Darken</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-darken.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Darken</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Darken</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-lighten">
+<title><guilabel>Lighten</guilabel></title>
+
+<para>
+The <guilabel>Lighten</guilabel> mode lightens the underlying layer while
+colorizing it to match the colors in the composited layer.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Lighten</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-lighten.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Lighten</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Lighten</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-hue">
+<title><guilabel>Hue</guilabel>, <guilabel>Saturation</guilabel> and
+<guilabel>Value</guilabel></title>
+
+<para>
+The <guilabel>Hue</guilabel>, <guilabel>Saturation</guilabel> and
+<guilabel>Value</guilabel> modes respectively apply the hue, saturation and
+value components of the composited layer to the underlying layer.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Hue</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-hue.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Hue</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Hue</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Saturation</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-saturation.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Saturation</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Saturation</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Value</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-value.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Value</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Value</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+<sect2 id="layers-composite-color">
+<title><guilabel>Color</guilabel></title>
+
+<para>
+The <guilabel>Color</guilabel> mode colorizes the underlying layer, yielding
+very strong colors.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>The gradient applied with the <guilabel>Color</guilabel> compositing
+mode</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mountains-color.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The gradient applied with the <guilabel>Color</guilabel> compositing
+mode</phrase>
+</textobject>
+<caption><para>The gradient applied with the <guilabel>Color</guilabel> compositing
+mode</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="layers-masks">
+<title>Layer Masks</title>
+
+<para>
+Basically, a layer mask is a mask that you place on your paint layer. This
+will literally mask areas of the layer, so that the content underneath shows
+through. You can paint on it with greyscale colors: the more black the color,
+the less the layer under it will shine through, the more white, the less the
+layer under it will be shown. So complete white will let nothing through,
+complete black will let everything through. Basically, it is a bit like
+selecting a piece of your image, and then cutting it, so that the selected
+bits go away. So what is the use for a mask here? The big advantage is that it
+is non-destructive: if you decide that you masked out the wrong part of your
+layer, you can easily remove the mask and start anew, something a lot harder
+(not to say near impossible, especially in between sessions) with regular
+selection-cutting.
+</para><para>
+So, how to create a mask? There are 2 ways:
+</para>
+
+<itemizedlist>
+<listitem><para>
+Start from scratch.
+<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Create
+Mask</guimenuitem></menuchoice>. The mask starts with everything being
+retained, that is, a complete white mask. Basically you will not see any
+changes as long as you do not paint on it. 
+</para></listitem>
+<listitem><para>
+Start from the current selection.
+<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Mask
+From Selection</guimenuitem></menuchoice>. The selectedness will be converted
+to whiteness. This means that fully selected area will be visible, fully
+unselected areas will be invisible, and the rest will be partially visible,
+depending on how much the area was selected. 
+</para></listitem>
+</itemizedlist>
+
+<sect2 id="layers-masks-editing">
+<title>Editing the mask</title>
+
+<para>
+First, make sure you are editing the mask, not the layer, by making sure
+<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Edit
+Mask</guimenuitem></menuchoice> is checked. (This is checked by default.) Then
+you can paint on the layer just like before, only now you are
+painting on the mask, instead of on the layer itself. To stop painting on the
+mask, you can uncheck the <guilabel>Edit Mask</guilabel> checkbox. There's
+also the option to show the mask, through checking
+<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Show
+Mask</guimenuitem></menuchoice>. (This is not checked by
+default). This option will render the entire layer as a visual representation
+of the mask in greyscale, instead of the actual layer. This can be handy to
+see where your mask is, but it might be not as handy when you want to edit it,
+since you cannot look at the actual layer.
+</para><para>
+Other actions: you can also remove the mask if you are not satisfied with it,
+and want to start over again, or just want to remove it, with
+<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Remove
+Mask</guimenuitem></menuchoice>. You can also <quote>apply</quote> the mask,
+meaning that the mask will be made permanently. This means that the mask is
+removed, but that its effect of transparency will be committed to the layer.
+</para>
+
+</sect2>
+</sect1>
+
+</chapter>