=============================================================================
= roLathe version 0.03 =================================  Toby Bryans 2026 =
=============================================================================

= Information ===============================================================

!roLathe is a lathe modeller. You draw the outline ("cut") of an object on
one side of an axis, and roLathe spins it around that axis to show the
solid it would make if it were turned on a lathe.

It is inspired by uLathe for Windows 3.1, and reads and writes the .lila
files of Little Lathe.

= Instructions ==============================================================

Double click on the !roLathe application icon. The application will be
loaded, an icon will appear on the icon bar, and two windows will open:

* The cut window, where the outline is drawn on a grid. The dotted line is
  the axis the outline is spun around.
* The render window, showing the spun object as a wireframe.

To edit the outline in the cut window:

* Click Select on an empty part of the grid to add a point to the end of
  the outline. Keep the button held down to drag it into place.
* Drag a point with Select to move it. Hold Ctrl while dragging to snap
  it to the grid.
* Click Shift-Select on a point to insert a new point halfway between it
  and the next one.
* Click Adjust on a point to delete it, or press Delete (or Backspace)
  to delete the selected point.

The point last clicked, added or dragged is selected, and drawn with a
black border; clicking Menu over a point selects it too. Edit point...
on the window menu, or Ctrl-E, opens the point editor for the selected
point (or the first point if none is selected). It shows the point's X
and Y in lila units, which you can change with the arrows (Select for
one way, Adjust for the other) or by typing and pressing Return; Tab or
the up and down arrow keys move between them. Previous and Next select
the neighbouring points. Changes show at once, and the editor follows
the point as you drag it. Close, or Escape, closes the editor.

Zoom on the window menu, or the + and - keys, show the cut at 100%, 200%
or 400%, for fine work. When zoomed in, use the scroll bars to move
around.

The render window follows the changes as you make them. In the render
window, drag with Select to turn the object (left and right) and tilt it
(up and down), and drag with Adjust up and down to zoom in and out.

The toolbar along the top of the render window sets the number of slices
(the number of steps the outline is turned through), either with the
arrows (Select for one way, Adjust for the other) or by typing a number
and pressing Return. Reset puts the view back to how it started.

The pop-up menu on the toolbar chooses how the object is drawn:

* Wireframe shows the lines of the mesh.
* Filled shades each face of the mesh in a single colour.
* Gouraud shades the object smoothly. Edges sharper than the file's
  sharpness setting stay sharp.

The Anti-alias option button smooths the jagged edges of the Filled and
Gouraud views, and of sprites saved from them. It is slower, so while you
are dragging, the view is drawn without it, and smoothed once you let go.

The Floor grid option button shows the floor the object stands on, as
in Little Lathe: a grid with lines every 8 units and heavier lines every
64, with the x axis in red and the z axis in blue. The object hides the
floor behind it. It is saved in the file, and shows in Drawfiles, sprites,
PNGs and prints too.

While the floor grid is shown, the cut window shows the floor as a green
line. As in Little Lathe, it starts under the lowest point of the
outline, and follows it as you edit. To raise or lower the floor, drag
the green line with Select by its left half (the left of the axis, as
clicks on the right add points); hold Ctrl to snap it to the grid. Drag
it back to the lowest point and it sticks there again. A floor that has
been moved is saved in the file; Little Lathe ignores it, and always
stands the object on the floor.

The colours, the shading and the direction of the light are set in the
Lighting window, opened by Lighting... on the window menu. Changes show
straight away and are saved in the file:

* Click on a colour (object, light, ambient or background) to choose it
  with the colour picker.
* Ambient shade (0 to 2) sets how far the ambient light reaches round the
  side of the object facing away from the light.
* Sharpness (0 to 1) sets which edges stay sharp in the Gouraud view: at
  0 every edge is smoothed; the higher it is, the more edges stay sharp.
* Scale (0.05 to 2) is the object's size in Little Lathe's world. The
  view always fits the object, so it shows as the object's size against
  the floor grid.
* Light direction shows the object (the black square) and the light (the
  yellow square) around it. Click or drag in it to move the light. The
  light turns with the object.

Ambient shade, Sharpness and Scale can be typed in (press Return) or changed
with the arrows, Select for one way and Adjust for the other.

Click Select on the icon bar icon to reopen the windows if they have been
closed. Click Menu on the icon bar icon for the Info window and Quit.

Click Menu over either window for:

* New, which starts again with an empty outline.
* Save, which leads to the usual save box. Drag the file icon to a
  directory display, or type a full path name and click Save. Choosing
  Save itself saves over the file it was loaded from or last saved to.
* Export, Drawfile, which saves a Drawfile of the window the menu was
  opened over: from the cut window, the outline, its mirror image and the
  axis; from the render window, the view as it is currently shown. Filled
  and Gouraud views are saved as flat shaded faces, since Drawfiles can't
  hold smooth shading.
* Export, Sprite, which saves the Filled or Gouraud view as a sprite.
* Export, PNG, which saves the Filled or Gouraud view as a PNG image, for
  use on other computers. PNGs are saved with a /png extension.
* Export, Scale, which sets the resolution sprites and PNGs are saved at:
  the screen's resolution, or 2, 3 or 4 times it, for a sharper picture.
  The menu shows the size each would be in pixels. Sprites can only be
  180, 90 or 45 dots per inch, so at the larger scales a sprite may show
  bigger than the window in other applications; PNGs record their true
  resolution.
* Edit point..., which opens the point editor (see above).
* Zoom, which sets the cut window's zoom (see above).
* Lighting..., which opens the Lighting window (see above).
* Print, which prints the window the menu was opened over on one page,
  scaled to fit and centred: from the cut window, the outline as it would
  be saved as a Drawfile; from the render window, the view as shown.
  Print is greyed out if no printer driver is loaded (start !Printers).

roLathe supports interactive help: run !Help and move the pointer over
its windows, icons and menus for a description of each.

Keyboard short cuts work once you have clicked in the cut or render
window (they get the input focus when roLathe starts):

  F3        Save, opening the save box at the pointer
  Print     Print the window
  Delete    Delete the selected point (in the cut window)
  Ctrl-E    Edit the selected point
  Ctrl-L    Open the Lighting window
  + and -   Zoom the cut window in and out

Files remember the view: when a file is saved, the render window's view
is saved with it (as Little Lathe's camera), and loading a file shows it
from the saved view. Little Lathe's own files open from the view they
were saved with in Little Lathe, as near as roLathe's view allows.

To load a lathe, drag a Little Lathe (.lila) file to the icon bar icon or
either window. Files are saved as Text, so any filetype is accepted when
loading, but the file must be in lila format.

When roLathe quits it remembers the positions of its windows, the cut
window's zoom, whether the render is shaded, Anti-alias and the export
scale, and starts the same way next time. They are kept in <Choices$Write>.roLathe.

roLathe asks before throwing away unsaved changes, whether by New,
loading another file, or quitting. Window titles show a * when there are
unsaved changes.

-----------------------------------------------------------------------------
 Version    | Comments
------------+----------------------------------------------------------------
 0.01       | First test build: icon bar icon, menu, Info window, cut window
 2026-10-14 | and wireframe render window.
------------+----------------------------------------------------------------
 0.02       | Phase 1 complete: windows resize up to the full screen, points
 2026-10-16 | can be added, dragged, inserted and deleted, and Little Lathe
            | files can be loaded, and saved from the window menu. New, and
            | checks before discarding unsaved changes.
------------+----------------------------------------------------------------
 0.03       | Phases 2 to 4: turn, tilt and zoom the view; toolbar with
 2026-10-16 | slices, Reset view, Wireframe, Filled and Gouraud shading,
            | and anti-aliasing. Export as Drawfile, sprite (up to four
            | times the screen's resolution) and PNG. Printing.
-----------------------------------------------------------------------------

= Acknowledgements ==========================================================

The .lila file format and the mesh generation come from Little Lathe:

  Little Lathe
  Copyright (C) 2019 Kostas Michalopoulos

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.

roLathe is an altered, rewritten version for RISC OS.

= Contact Details ===========================================================

eMail : toby-riscos@bryans.org
