<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY dp "<application>DrawPile</application>">
]>

<book lang="en">
<bookinfo>
<title>DrawPile User Guide</title>
<author><firstname>Calle</firstname><surname>Laakkonen</surname></author>
<copyright><year>2008</year><holder>Calle Laakkonen</holder></copyright>
</bookinfo>

<!--
<preface><title>Preface</title>
<para>TODO</para>
</preface>
-->

<chapter id="introduction"><title>Introduction</title>
<para>
&dp; is a drawing program with a twist. &dp; allows multiple users to connect together and simultaneously draw on the same image.
</para>
</chapter>

<chapter id="gettingstarted"><title>Getting started</title>
<sect1 id="starting"><title>Starting &dp;</title>
<screenshot>
<mediaobject>
<imageobject> <imagedata fileref="img/mainwindow.png"/> </imageobject>
<caption><para>Main window</para></caption>
</mediaobject>
</screenshot>

<para>When you first start &dp;, you are presented with a blank main window. To start drawing, create a new blank image using the new button or load an existing picture.
</para>
<para>On the right, you can see some of the dock windows. From the brush settings dock you can configure the drawing tools. Right below are the color picking docks (RGB, HSV, and a customizeable palette.) The bottom-most dock displays the list of users when connected to a network session.</para>
<para>On the bottom of the drawing area is a handle which reveals a chat box when dragged.</para>
</sect1>

<sect1 id="hosting"><title>Hosting a session</title>
<screenshot>
<mediaobject>
<imageobject> <imagedata fileref="img/host.png"/> </imageobject>
<caption><para>Hosting dialog</para></caption>
</mediaobject>
</screenshot>

<para>Hosting allows you to share your drawingboard with other users. By default,
&dp; will automatically start a server in the background to allow others to
connect to your computer. It is also possible to set up a server on a remote
computer and host a session there. Note. You can only host one session at a time using the built-in server. If you want to host multiple session on the same computer, you need to start the server manually on a different port.
</para><para>
You can set the following session options:
<itemizedlist>
<listitem><simpara>Title: this is shown in the title bar. May be left blank.</simpara></listitem>
<listitem><simpara>Username: your username.</simpara></listitem>
<listitem><simpara>Password: a password for this session. If left blank, no pasword will be required.</simpara></listitem>
</itemizedlist>
The following settings are available in the Advanced tab:
<itemizedlist>
<listitem><simpara>Maximum number of users: the user limit for the session</simpara></listitem>
<listitem><simpara>Allow drawing: if this option is unset, new users will be locked by default.</simpara></listitem>
</itemizedlist>
</para><para>
Hosting a session makes you its owner. This means that session administrations
commands are available to you. See the <link linkend="sessionadmin">session administration</link> chapter for details.
</para>
<caution><para>When hosting using the built-in server, the address displayed in the status bar of the main window may not be accurate! A computer can have multiple IP addresses, only some or one of which is visible to the Internet, and DrawPile tries to make an educated guess which is the most likely to work.</para></caution>
</sect1>

<sect1 id="joining"><title>Joining a session</title>
<screenshot>
<mediaobject>
<imageobject> <imagedata fileref="img/join.png"/> </imageobject>
<caption><para>Join dialog</para></caption>
</mediaobject>
</screenshot>
<para>To join a drawing session, enter the address of the host in Host address
field. Username should not be left blank.
</para>
</sect1>
</chapter>

<chapter id="sessionadmin"><title>Session administration</title>
<sect1 id="locking"><title>Locking</title>
<para>The drawing board can be locked to prevent users from making changes.
You can quickly lock the board for all users (yourself included) by clicking
<guimenuitem>Lock the board</guimenuitem> from <guimenu>Session</guimenu> menu.
</para>
<para>Individual users can be locked by clicking on the lock symbol
next to the user name in the user list.
</para>
<para>Note that the general board lock and user locks are separate. Lifting the general lock will not unlock users that have been individually locked.</para>
</sect1>

<sect1 id="kicking"><title>Kicking</title>
<para>Unruly users can be kicked from the drawing session by clicking on the
X symbol next to the user name in the user list.
</para>
</sect1>
</chapter>

<chapter id="tools"><title>Tools</title>
<sect1 id="pen"><title>Pen</title>
<para>The pen tool draws hard lines with no antialiasing. It is useful for
pixel-art and filling large areas efficiently.</para>
</sect1>
<sect1 id="brush"><title>Brush</title>
<para>The brush works much like the pen tool, except it always draws with
soft antialiased strokes. You can also adjust the hardness of the brush.</para>
</sect1>
<sect1 id="eraser"><title>Eraser</title>
<para>The eraser tool currently works like the brush, except it draws with
the background color. You can disable antialiasing by toggling the hard-edge button.</para>
</sect1>
<sect1 id="colorpicker"><title>Color picker</title>
<para>Allows you to pick colors from the image by clicking on it. The
picked color will be set as the foreground color. Since this tool doesn't change the image in any way, it can be used even when the board is locked.</para>
</sect1>
<sect1 id="line"><title>Line &amp; Rectangle</title>
<para>These tools allow you to draw straight lines and rectangles. You can toggle antialiasing for the line tool. Pressure sensitivity is not supported for these tools.</para>
</sect1>
<sect1 id="texttool"><title>Annotation tool</title>
<para>This is a special tool for adding text boxes onto the image. The text layers float above the image and can be modified. A text layer can be rasterized and 'baked' on the image. Annotation baking is disabled in online mode. Note that annotations cannot be saved at the moment.</para>
</sect1>
<sect1 id="toolextra"><title>Tool options and blending modes</title>
<para>All tools, except for the color picker and the annotation tool, share some basic options. The size, opacity, hardness and spacing can be adjusted, as well as sensitivity to stylus pressure (on supported devices only.)</para>
<para>Some tools can be switched between smooth and hard edged modes. The pen and rectangle tools always operate in hard-edge mode.</para>
<para>The blending mode affects how the color of the brush is blended with the picture.</para>
<table><title>Blending modes</title>
<tgroup cols='2' align='left'>
<thead>
<row>
	<entry>Mode</entry>
	<entry>Explanation</entry>
</row>
</thead><tbody>
<row>
	<entry>Normal</entry>
	<entry>Blend brush with the base color.</entry>
</row>
<row>
	<entry>Multiply</entry>
	<entry>The colors are multiplied together. This results in a darker color.</entry>
</row>
<row>
	<entry>Divide</entry>
	<entry>The base color is divided ith the brush color. This results in a lighter color.</entry>
</row>
<row>
	<entry>Burn</entry>
	<entry>Increases contrast, darkening the color.</entry>
</row>
<row>
	<entry>Dodge</entry>
	<entry>Decreases contrast, brightening the color.</entry>
</row>
<row>
	<entry>Darken</entry>
	<entry>Darkens the picture to match the brush color.</entry>
</row>
<row>
	<entry>Lighten</entry>
	<entry>Lightens the picture to match the brush color.</entry>
</row>
<row>
	<entry>Subtract</entry>
	<entry>Subtract the brush color from the base color.</entry>
</row>
<row>
	<entry>Add</entry>
	<entry>Add the brush color to the base color.</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>

</chapter>

<chapter id="technical"><title>Technical details</title>
<sect1 id="techsync"><title>Synchronization</title>
<para>The problem with a network drawing program like this, is how to keep
all the users in sync? Transmitting pixel data everytime something is changed
would consume too much bandwidth to be usable, so the obvious solution is to
only transmit the drawing commands.</para>
<para>The next problem is, what happens when two or more users draw in the same
spot at the same time? If each user would first draw on their own board and then
send information about the stroke to others, each would get the strokes in
a different order. The solution to this problem is to use a server that
acts as a traffic controller. Users send all drawing commands to the server
and never draw anything directly. The server distributes the commands in the
same order to each user who then commit them to their boards.</para>
<para>This all works when the users have been in the session before anyone
has started drawing yet. To allow new users to join in the middle of a session,
the server selects a single user and request it to send a copy of its board
contents to the new user.</para>
<para>To get a board snapshot at a known state, each user will be temporarily
locked when a new user joins. The lock is a graceful one, it won't take place
until the client has finished any stroke that might be in progress.</para>
<para>When each user has been locked
<footnote><para>In parallel computing, this method of synchronization
is known as a "barrier"</para></footnote>
, the board snapshot is made and regular operation is resumed.</para>
</sect1>
</chapter>

</book>

