==== LRSKETCH MANUAL                               ====

LRSketch is a graphic raster editor program made with
the suckless philosophy in mind, and with major
influence from drummyfish's own philosophy of "less
retarded software". Due to the design philosophy of
LRSketch, it does not have things that other,
'mainstream" programs would have by default, like
anti-aliasing, 24-bit / 32-bit / float color support,
palettes, effects, patterned flood fill, in-image
text boxes, measuring tools, Python support, etc.
This is a simple digital art tool made for spriting,
sketching, and generally making what one may call
"suckless" art.

LRSketch is more of a drawing tool than a general
image manipulator. It comes with features to perform
rudimentary image manipulation (e.g. color replace,
copy/paste) but it was moreso designed for making
art, and these features supplement it.

==== FEATURES                                      ====

By default, LRSketch has the following capabilities:

- Fully free software in the public domain, all
  original and borrowed code / assets are under the
  Creative Commons Zero + a waiver.
- Minimalist and portable design inspired by suckless
  and LRS (less retarded software); RGB565 only,
  platform agnostic code, C99, only essential drawing
  modes, etc.
- Highly customizable via settings.h in source code
- Dynamic multi-resolution support, maximum modifiable
  in settings
- Saving and loading to either raw PPM P6 or a custom
  16-bit LRSP format
- GUI-less menu for allowing full usage with only 6
  mandatory keys

Patches and some frontends can also extend the
function of LRSketch through binding the optional
keys, extending certain events, or by modifying the
program itself.

==== CONTROLS                                      ====

== OUT OF MENU                                       ==

When the menu is closed, you are able to modify the
loaded image. How you are able to modify the image
depends on your currently select mode, shown at the
bottom left of the screen. When starting the program,
the default mode is "freedraw". Modes can be thought
of as tools one would find in a "regular" drawing
program.

Each of the modes have different functions. Some (e.g.
freedraw) work when holdin the draw key. Others (e.g.
pick) don't. Here is a basic rundown of how each mode
works:

- FREE continously draws in the path the cursor moves.
  If PNT_CONTINUOUS_DRAW is 0, it simply places a
  single brush pixel down instead of pathing across
  the previous cursor position.
- PICK sets the current brush color to the color of
  the image pixel the cursor is currently on. It only
  changes the color per press of the draw key.
- REPLACE acts like a mix of FREEDRAW and PICK: when
  first selecting the tool you must pick a color to
  draw over. Once done, the tool acts like FREEDRAW,
  except it only draws over pixels that have the same
  color as the one you picked. This is good for e.g.
  shading.
- FILL performs a flood fill starting from the cursor
  position. This only fills once per click, and has
  no effect if the color being filled is the same as
  the color to fill with.
  **NOTE**: Fill doesn't work well for concave
  shapes at the moment!
- COPY copies a region of the image to the clipboard.
  The first click sets the start point. The second
  click sets the end point and attempts to copy the
  region. If the region is too big (check the
  PNT_MAX_CLIP_RESOLUTION_* macros in settings.h!)
  the copy will not work.
- CUT acts like COPY, except it fills the area in
  with the PNT_STARTING_IMAGE_COLOR color as it
  copies.
- PASTE copies the clipboard contents back to the
  image.
- LINE draws a line between 2 points, placing brushes
  along the line. It uses the same "set points"
  system as the COPY and CUT modes.
- RECT draws a rectangle using 2 points. It uses
  the same "set points" system as the COPY and
  CUT modes.
- CIRCLE draws a circle using 2 points. It uses the
  "set point" system that the other shape tools use.
- PAN translates cursor movement into image
  movement. The draw key does nothing in this
  mode.

Pressing the menu key will enter the menu, starting at
the main menu.

== IN MENU                                           ==

While in the menu, your controls are limited to it.
The up and down keys navigate the menu. The left and
right keys, if over a menu item with a number beside
it, will increment or decrement the value. Some will
respond to the keys being held, others won't.

The most important menu is the main menu. This is
where one can access every feature the program has to
offer.

- NEW IMG clears the image and sets it to the
  starting resolution
  (see PNT_STARTING_IMG_RESOLUTION_* macros in
  settings.h)
- SAVE IMG and LOAD IMG take you to a file format
  selection menu, which will save or load the selected
  format to/from the data file.
- SET COLOR takes you to a menu where you can set
  the R, G, and B values of your brush's color.
- DRAW MODE takes you to a menu where you can pick
  any of the draw modes.
- SIZE sets the brush size, the limits being
  as low as 1 and as high as 255.
- ZOOM sets the image zoom by increments of 1 pixel.
  Good in case the optional zoom keys aren't bound or
  you need precision.
- IMG WIDTH and IMG HEIGHT change the size of the
  currently loaded image.
  **NOTE**: Changing image resolution of an image
  that is already drawn on causes unusual effects!
  This bug is present as of v0.7.

Pressing the menu key at any time will leave the menu
and return you to the image.

==== KEYBINDS                                      ====

By default, all frontends should have 6 keys at least;
the up, down, left, right, draw, and menu keys. These
will be bound differently based on the platform (e.g.
a game console may use the D-pad, A and start) but
all frontends will have these 6 basic keys that enable
full functionality of the program.

Platforms with more keys / buttons can bind some or
all of the many optional keys that enable easy access
to certain functions, saving time browsing the menu.

On PC frontends you may find the following controls.
These are designed for QWERTY keyboards, with or
without numpads, use no modifier keys, and are made
to be relatively ergonomic for those who control
their mouse with their right hand.a

  - ARROW KEYS = Up, down, left, right
  - WASD = Move image
  - Z or LEFT CLICK = Draw
  - ESCAPE = Menu
  - Q = Decrease brush size
  - E = Increase brush size
  - F = Pick color at cursor position
  - 1 = Zoom in by 16
  - 2 = Zoom out by 16
  - B = Switch to "freedraw" mode
  - R = Switch to "replace" mode
  - Y = Switch to "pick" mode
  - G = Switch to "fill" mode
  - H = Switch to "pan" mode
  - X = Switch to "cut" mode
  - C = Switch to "copy" mode
  - V = Switch to "paste" mode
  - 3 = Switch to "lines" mode
  - 4 = Switch to "rect" mode
  - 5 = Switch to "circle" mode

Some platforms, namely PC ones, may also provide mouse
support. Due to the nature of certain frontends, mouse
behavior may not be identical between them.

==== SAVING AND LOADING                            ====

LRSketch, by default, doesn't operate with the typical
file saving schema of "ask for a filename and a file
extension". Instead, it reads from and writes to a
single data file. How the file is handled depends on
the frontend used. For instance, PC frontends may use
"data.img" as their data file, and clear it when being
saved to.

The program provides 2 default file formats: a custom
LRSP format, and raw PPM P6. LRSP stores 16-bit color
and is basically as close to image data in RAM as it
can get, while PPM saves a 24-bit raw PPM P6 file.
Note that PPM may be subject to color conversion
inaccuracy from RGB565 to RGB888. If you're conscious
of this and/or the slightly larger file size, you may
want to use LRSP.

Frontends can alter how file behavior works; they can
either disable it due to incompatibility, provide the
typical data file, or extend it by opening different
files based on the chosen format, like "data.lrsp",
or opening a prompt to ask for a file.

==== RUNNING                                       ====

LRSketch is typically distributed in source code
format as the main way of configuring the program is
through the source code, specifically the settings.h
file. Assuming you have libraries for a compatible
frontend, you can run make.sh with a frontend as
an argument to compile the program. Running it should
be as easy as doing ./lrspaint or double-clicking on
it.

If you wish not to use make.sh, the program can be
simply compiled by running a C compiler on one of the
main_*.c files and linking the necessary libraries.

Should your platform or library not have a frontend
file, you can port the program to it yourself by
making a main_platform.c file, setting up the
library, and following porting instructions given in
the comments of paint.h.

==== TIPS AND NOTES                                ====

- Check settings.h to fine-tune the program for your
  work! It includes macros for max image / clipboard
  size and flood fill seed point count.
- Is the fill mode causing weird artifacts? Try
  increasing PNT_SEED_POINTS in the settings. It
  allocates more seed points for the flood fill mode,
  making errors less frequent, at the cost of slightly
  higher RAM usage.
- Use all the modes and tools! Each of them have at
  least some sort of use, which can stand in for the
  more conventional features of "modern" drawing
  programs, even if it means more manual labor.
  For instance, the "Replace" mode can act as a
  fill tool, and the "Copy" and "Paste" modes can
  apply patterns.
- Check the patches folder for program modifications
  that may help you, like undo/redo. If you know a
  good bit about C, raster image formats, and then
  some, you can try adding features yourself, and
  share then with others as .diff patches.

==== LICENSING                                     ====

LRSketch is put into the public domain via the
Creative Commons Zero, alongside a waiver of remaining
rights as seen below. For more information, view
README.md.

Each contributor to this work agrees that they waive
any exclusive rights, including but not limited to
copyright, patents, trademark, trade dress, industrial
design, plant varieties and trade secrets, to any and
all ideas, concepts, processes, discoveries,
improvements and inventions conceived, discovered,
made, designed, researched or developed by the
contributor either solely or jointly with others, which
relate to this work or result from this work. Should
any waiver of such right be judged legally invalid or
ineffective under applicable law, the contributor
hereby grants to each affected person a royalty-free,
non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to this right.
.
