(You're viewing the automatic text conversion of the StrongHelp manual, which
means you either don't have StrongHelp or didn't set it to be looked at on
bootup.  If possible, you should view the original instead.  It really is
much nicer.  I thought I'd better start providing one of these cos it doesn't
look as if StrongHelp'll be made ARMv7 compatible any time soon.)

                                  Cogs manual
                                  ~~~~~~~~~~~

  Introduction  Reference manual  Known issues
  Quick guide   Patterns          History
  ----------------------------------------------------------------------------
                    Cogs 2.00 by Martin Bazley - Formalities
  ============================================================================

                                   Introduction
                                   ~~~~~~~~~~~~

    Did you ever play with a Spirograph set when you were younger?  If you
    didn't, here's a brief explanation, and if you did, here's a brief
    explanation anyway: There were a number of different-sized gears with
    holes in just big enough to push the point of a pen through, and these
    gears fitted into larger 'templates' (circular holes with teeth round the
    inside).  You pushed your pen through a hole in a gear and rotated the
    gear around the plate.  One of many things may then have happened, one of
    which involved the production of an amazing geometrical pattern and most
    others of which involved curse words and, if necessary, Sellotape.

    Cogs is a Spirograph simulator and so much more.  Chiefly, as well as
    being able to faithfully reproduce the original patterns in electronic
    (and slip-free) form, it is also not bound by those pesky laws of physics
    which hinder the puny inhabitants of meatspace.  So, for example, you can
    have a second gear rotating inside the first one, and you can have a gear
    which is larger than the one it is supposedly rotating inside.  And then
    you can have a third gear rotating inside (or outside) the second, and so
    on.

    If the toy could keep you amused (or frustrated) for an hour, Cogs can
    keep you inside all weekend...
    ==========================================================================

                                   Quick guide
                                   ~~~~~~~~~~~

    Click on the Cogs icon bar icon to open the Choices window.  The default
    settings will produce a seven-pointed pattern - press Draw to see it.
    The black and white pattern display will open, and the pattern will begin
    drawing.  After it has finished, click MENU over this to bring up a menu
    with two entries - Save Sprite and Save Draw.  These produce save boxes,
    from which you can drag files to directories or icons like with any other
    save boxes.

    Different patterns can be produced by altering the values in the 'Teeth'
    column, and more complex patterns can be produced by clicking down the
    list of radio icons (note that Cogs will refuse to draw any pattern which
    has a teeth value of 0 in it).  On the right-hand side, 'Hole distance
    from edge' can be used to sharpen or soften the points in a pattern,
    'Tooth size' zooms in and out, and 'Multitasking level' can be reduced to
    see more of the pattern being drawn (at the expense of speed) or set to 0
    to single-task.

    The main rule for finding good patterns is experimentation, but as a
    rule, anything with a very large value in the 'Total' field will be a
    lengthy disappointment.
    ==========================================================================





                                                                        Page 1
                                 Reference manual
                                 ~~~~~~~~~~~~~~~~

    Terminology and principles
    The Choices window
    Keyboard shortcuts
    Foolproofing
    Saving options
    ==========================================================================

                             Terminology and principles
                             ~~~~~~~~~~~~~~~~~~~~~~~~~~

      The principal concept involved in my not-very-like-a-Spirograph
      extended program is that of the 'circle'.  There can be up to ten of
      these, and each one is defined as rotating around the edge of the
      previously-numbered circle, except the first, which remains stationary.

      Circles here replace the Spirograph gears, and you are expected to
      imagine where the teeth are on the deceptively smooth surface.  One
      tooth is the smallest possible unit of rotation, and each wheel has its
      own number of teeth defined, which means wheels take different amounts
      of time to rotate the same distance.  This is at the heart of the
      amusing patterns produced.

      In non-virtual reality, a pattern is produced by rolling the wheel
      around the inside of the template so that the teeth mesh together, with
      a pen held down inside one of the holes in the wheel to record its
      journey.  The pattern is finished when the end of the line drawn meets
      the beginning.

      Here, circles are allowed to rotate around each other, as well as
      around the unmoving template (which is represented by circle 1).  The
      default parameters have only two circles (same as a real-life
      Spirograph set), with a 'wheel' of 75 teeth rotating around a
      'template' of 105 teeth.  The virtual 'pen' is placed 24 OS units from
      the edge of the wheel.

      If all that passed you by, I find the best way to learn is to open the
      preview window, position the caret in the 'Start pos' icon and hold
      down Ctrl-Up to increment it and watch the circles rotate.


      ========================================================================

                                 The Choices window
                                 ~~~~~~~~~~~~~~~~~~

      Here are arranged a delightful array of configuration options, to allow
      you to produce all the patterns you desire.

      As well as the buttons described here, the choices window also supports
      a number of keyboard shortcuts.  Interactive help is also available.

      If in doubt, the Preview button is your friend.

      Circle options

      The radio buttons arranged down the side of the group box configure the
      number of active circles, up to a maximum of 10.  Inactive circles have
      their settings remembered for the next time they become active.

      The number of teeth in the circle is controlled in the second column.

                                                                        Page 2
      This is what produces the different patterns.  Alter one of these if
      you're not sure what to do.

      The informational column on the left gives the radius of that circle in
      OS units.  This is dependent on both the number of teeth and the
      current tooth size.

      The third column allows you to rotate individual circles, e.g. to start
      with the hole facing towards the centre rather than the edge.  This can
      be positive or negative, but values which exceed the number of teeth
      are pointless, as they represent a rotation of more than 360 degrees,
      and will be automatically set to the lowest equivalent.

      Other options

      The two writable icons in the 'Hole distance' box, which are linked to
      each other (altering one alters the other), control the position of the
      pen, relative to the edge of the highest-numbered circle and given in
      OS units.  (This is why you need to know the radius.)

      The length of the pattern (the number of teeth it needs to rotate by in
      order for the pen to reach its start position) is given by the the
      'Total' field, which is the least common multiple of all the teeth.

      The 'Start pos' and 'End pos' icons allow less than the whole pattern
      to be drawn - if, for example, you want to colour sections differently,
      with the aid of DrawComb.  They are measured in the same units as the
      pattern length.  Start position cannot be lower than -total, and cannot
      be higher that end position-1.  End position cannot be lower than start
      position+1, or higher than +total.  Additionally, the difference
      between start and end positions cannot be greater than the total
      (otherwise bits of the pattern would get drawn twice).

      The tooth size is the size, in OS units, of a single 'tooth' (the unit
      the number of teeth is measured in).  In practice, changing this value
      changes the ratio of radius to number of teeth, and provides a
      primitive zoom function.

      The multitasking level is the number of positions plotted between Wimp
      polls when drawing the pattern.  In layman's terms, increasing it means
      Cogs uses more desktop time, and you see less of the plotting process,
      but it gets the job done faster.  As this is measured in the same units
      as the total positions, increasing it beyond the difference between
      start and end positions will produce single-tasking.  The program can
      be set to single-task automatically by setting this value to 0.

      The buttons

      'Auto update' is an option button which, when switched on, will cause
      the 'End pos' value to be automatically set to the total whenever a
      value in the teeth column or the number of circles changes.  Normally
      you would have this switched on, else whenever the pattern length
      increased, some of it would fail to be drawn.

      'Preview' opens the preview window.  This shows the position of all the
      circles, as configured by the current contents of the choices window,
      and the position of the hole.  This is useful for seeing the effect of
      changes to the rotation and start position values.  You can also get a
      good idea of how the pattern will be drawn by incrementing the 'Start
      pos' value while the window is open.

      The preview window uses separate configuration from the pattern window,
      so the two do not conflict if both are open at once and showing

                                                                        Page 3
      different settings.

      'Draw' commences the drawing process.  Depending on how long the
      pattern is (determined by the 'Total' field), this might be instant, or
      it might be very, very slow.  Multitasking also slows things down
      considerably, but at least allows you to see the progress it is making.

      The pattern window will open, and show the graph either being drawn or
      in its finished state.  Clicking on the 'Draw' button with different
      settings while the graph is still being drawn will cancel that one and
      start the new one instead.

      If the settings are unchanged since the last time the button was
      clicked, the pattern window will simply reopen rather than
      recalculating anything.  This also applies if the pattern is still
      drawing.

      While Cogs is drawing, a percentage hourglass will let you know how far
      it has got.
      ========================================================================

                        How to find the least common multiple
                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Predefine an array to three dimensions.  Take two numbers, wash
        thoroughly and dry off well.  Dice them into little prime factors (I
        recommend writing all the prime numbers to an array first, to make
        this bit easier), taking care to keep count of how many you have of
        each.  Sort them by size, and sweep off any ones belonging to one
        number of which there are more, identical, ones belonging to the
        other (keep them around the house, because you never know when that
        sort of thing comes in useful).  Multiply all the remaining numbers
        together, cover with puff pastry and you have a very nice Least
        Common Multiple of the two numbers you started with.  Serves none.

        I had to boast about knowing that somewhere, because it was such a
        pain to implement.
        ======================================================================

                                 Keyboard shortcuts
                                 ~~~~~~~~~~~~~~~~~~

      A number of keyboard shortcuts are provided when the choices window has
      the input focus, for your convenience:

      Tab Cycle caret through icons, left to right.
      Shift-Tab     Cycle caret through icons, right to left.
      Down     Cycle caret through icons, top to bottom.
      Up  Cycle caret through icons, bottom to top.
      Ctrl-Up  Increment value in writable icon by 1, if possible.
      Ctrl-Down     Decrement value in writable icon by 1, if possible.
      Page Down     Increment number of circles by 1.
      Page Up  Decrement number of circles by 1.
          (These two are reversed so as to correspond to the layout of the
          radio buttons.)
      Ctrl-P   Open preview window.
      Return   Open pattern window/start drawing.
      ========================================================================






                                                                        Page 4
                                    Foolproofing
                                    ~~~~~~~~~~~~

      As from version 2.00, Cogs is much more tolerant of the values it is
      willing to interpret.  The distance of the hole from the centre, for
      example, can now be zero or greater than the wheel radius (the latter
      used to crash, whereas I just couldn't find a reliable way of
      calculating the net size of the former).  However, there are two
      remaining circumstances in which clicking on the 'Draw' button will
      have no effect other than producing an error box saying "This
      configuration is impossible to draw":

         Any one of the numbers of teeth is 0.  This doesn't really mean
          anything, so it can't draw it.  This will also cause the preview
          window to show nothing but a blank.
         The total number of positions is so great it cannot be represented
          in BASIC's 31 bits.  This is represented by the 'Total' field
          containing nothing but a "0", which is red, so you know something's
          gone horribly wrong.  As the preview function doesn't need to know
          about this, it can represent the wheel positions, but you won't be
          getting a pattern.

         Apart from these, a lack of memory is possible, and if this
          happens, as well as displaying a warning, the pattern display will
          close and cannot be reopened until the 'Draw' button is clicked
          with sufficient memory free.  This is because the parameters have
          already been read by the time the program discovers they are
          undrawable.
      ========================================================================

                                   Saving options
                                   ~~~~~~~~~~~~~~

      Clicking MENU on the pattern window will produce, surprisingly enough,
      a menu.  This allows you to save the pattern as a sprite or a drawfile.

      The sprite save simply writes the internal sprite area to disc, and for
      this reason is very quick.  It also tends to produce smaller files (as
      everything is in 1-bit monochrome) than the Draw option, except with
      either very simple or very large patterns.  On the other hand, there
      isn't much you can do with it.

      The drawfile save calculates the pattern again, writing the coordinates
      to a drawfile (with the aid of the MakeDraw library) instead of the
      screen.  This takes just as long again as it did to draw the pattern in
      the first place, and doesn't multitask.  Drawfiles, on the other hand,
      are a lot more versatile, and can be used to spruce up your patterns,
      or scale them.  (Like this.)#url
      http://homepages.nildram.co.uk/~riscos/Album9/index.htm>

      Saving as Draw requires the program to claim quite a lot of extra
      memory, so if that isn't available it'll complain and not write
      anything.

      Two extra options are available in the drawfile save box:

      The 'Accuracy' icon controls the size of the gaps left between points -
      the default of 4 will plot only every 4th point, and average the rest
      with bezier curves.  Higher values are less accurate, but produce
      smaller files.  A value of 1 will turn off bezier curves and simply
      plot every point with straight lines, as the screen plotter does.

      The 'Line width' icon allows you to specify the with of the path used

                                                                        Page 5
      to plot the graph, in points.
      ========================================================================

                            Patterns to watch out for
                            ~~~~~~~~~~~~~~~~~~~~~~~~~

    This section is outdated and applies to versions prior to 2.00.  If
    anybody encounters anything interesting after that, send it to me and you
    too could be featured on this obscure manual page of an obscure program!

    The accomplished user of this program can create an amazing variety of
    patterns on demand.  Here is a brief guide to some interesting parameters
    to try.  It may well not be comprehensive - I'll add new things as I
    discover them!

    Wheel teeth   The only valid way left of drawing a perfect circle.
    Plate teeth   A classic Spirograph combination, seen here in its
                  much-drawn form with the aid of the start and end
                  positions, DrawComb and Draw.
    Plate teeth  wheel teeth    A combination of two patterns with identical
                                 plate teeth values and wheel teeth the same
                                 amount either side.  Works best with the
                                 hole difference at 0, as here.
    Total cycles  The wheel teeth is an exact divisor of the plate teeth,
                  resulting in a geometrical shape.
    Total rotations    The wheel teeth is the plate number multiplied by
                       something - the bigger, the more crossovers it has.
    Plate teeth   An extreme example of the above.  One of my favourites.
    Hole radius   How to draw a pattern with no hole in the middle - only
                  works for more than half the number of plate teeth though.
    Hole difference    A somewhat easier way of achieving the same effect
                       with more wheel teeth than plate teeth.

    By the way, for anyone wanting to recreate the original patterns, the
    original set of wheels was: 24, 30, 32, 36, 40, 42, 45, 48, 50, 52, 56,
    60, 63, 64, 72, 75, 80 and 84.  The two plates were 96 and 105, with 432
    teeth around the border.  A hole difference of twice the tooth size is
    roughly equivalent to the outermost hole on a real wheel.
    ==========================================================================

                      A short guide to undocumented features
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

       I'm still not 100% confident about the accuracy of the new routines,
        so don't take anything I say at face value.
       The circles in the preview jitter a bit, probably because of floating
        point errors (although it's a lot better than it used to be).
       The new foolproofing hasn't been tested as thoroughly as it might
        have been, so if you manage to get it to crash, please let me know.
       Need to find some new patterns to go in the gallery - send me any
        interesting ones you find!
       MakeDraw seems to take it upon itself to set the paper size, and I
        can't be bothered to figure it out, so if your pattern is larger than
        a certain radius it won't be centred in the drawfile.
       I'm not 100% convinced as to the robustness of the memory allocation
        when there is not enough to be had.  Deliberately torturing the
        routines seems to produce mysterious errors on occasion.
        ("Privileged mode stack overflow detected" on a call to OS_SpriteOp?
        Well, why didn't you complain about that when you granted the
        necessary memory allocation, then?)
       If the size of the pattern is smaller than the minimum size of the
        window, the spare space won't be automatically redrawn and can
        contain elements of the previous pattern.  Dragging another window

                                                                        Page 6
        across it fixes it.

    Future plans

       RAM transfer could theoretically be added, now I've got my memory
        allocation sorted out.
       Possibly add some option to save the raw parameters as well as a
        pattern?
       And load them back in again?  (This would require considerably more
        work.)
       Does anyone want an icon which tells you how large the pattern
        display is going to be?
       Need an easier way to stop drawing a pattern in the middle.
        (Although at least there is a way now.)
       Remove dependency on MakeDraw and write own goddamned Draw routine.
        Principle blocker here is inability to calculate control points and
        bounding boxes of smooth bezier curves.
    ==========================================================================

                               Cogs version history
                               ~~~~~~~~~~~~~~~~~~~~

    As of 23rd November 2009, Cogs is distributed under the terms of the GNU
    General Public License version 3.

    Version 1.00
    Version 1.10
    Version 1.20
    Version 1.21
    Version 1.22
    Version 2.00
    ==========================================================================

                            Version 1.00 (2nd June 2008)
                            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         There does not appear to be any history yet.
      ========================================================================

                         Version 1.10 (13th December 2008)
                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         Added proper redraw cacheing.  Phenomenal speed increase visible!
         Added interactive help.
         Added 'Help...' option to icon bar menu.
         Removed unnecessary indenting throughout !RunImage.
         Removed unnecessary call to Wimp_GetWindowState in pattern plotter.
      ========================================================================

                         Version 1.20 (31st December 2008)
                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         General large-scale reorganisation of !RunImage to make maintenance
          easier and better adapt Martyn Fox's code for my own use.
         Rewrote error handler so that it is no longer necessary to
          interrupt the program to display a warning.
         Lots of miscellaneous syntax consistency corrections.
         Cogs can finally save its patterns to file!  Sprite or Draw
          variants available.
         Toughened up dynamic areas slightly.  If your machine, for whatever
          reason, can't spare a poor old program 8KB of address space at the
          start, dynamic areas will be disabled rather than crashing.
         Lots of new options - tooth size, start and end positions and

                                                                        Page 7
          rotation.
         Due to the above, it was no longer practical to constantly check
          whether a pattern is valid and grey out the 'Draw' button
          appropriately.  Values outside the limits will now be automatically
          set to the limits.  An error box will come up in extreme
          circumstances.
         Now capable of determining the length of a pattern before drawing.
         Completely changed the structure of the actual pattern-drawing.  As
          well as accommodating the new Draw code, the previous hit-and-miss
          implementation has been replaced with a straight FOR loop made
          possible by the above.
         Also thanks to the above, there is a percentage hourglass to watch
          during long patterns.
         Corrected the initial redraw code - which was apparently only
          working very tenuously in the first place!
         Renamed one of the two(!) 'Hole radius' icons in the main choices.
         Had to substantially increase the wimpslot.
         Rewrote the !Help file as a StrongHelp manual.
         The midnight chimes rang out just as I typed that last sentence.
          Happy New Year, everybody!
      ========================================================================

                           Version 1.21 (14th March 2009)
                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         Corrected various aspects of the Data Transfer Protocol.  Notably,
          finally fixed dragging to the icon bar!
         'Fixed' system font problems.  Seriously, complain to ROOL if it
          matters.
         Corrected horrible mistake in menu clicking, which shouldn't have
          worked in the first place...
         Corrected horrible mistake in dynamic area initialisation, which
          definitely wouldn't have worked on an A5000...
         Now opens main menu over both choices windows.
         Moved 'Auto update' to main menu.
         New advanced display informing you of the maximum useful 'Plate
          start' value.  Also enforced it.
         String termination routine is much less antisocial in matters of
          memory writing now.
         Moved version string, errors, menus and interactive help into a new
          Messages file.
         Internationalised application.
      ========================================================================

                           Version 1.22 (14th March 2010)
                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         Fixed bug which caused certain parts of the screen to mess up after
          clicking on the 'Draw' button.
         Removed the 'Redraw screen' menu option.
      ========================================================================

                          Version 2.00 (3rd January 2011)
                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         Where to start?  Basically rewrote everything.
         Wheels within wheels (up to ten levels deep) are now possible.
         All options are now contained in the same choices window.
         Added a preview window which tells you how the wheels are laid out.
         The drawing process now multitasks.
         The pattern display finally has scrollbars and an adjust size
          button.
         No longer uses dynamic areas.

                                                                        Page 8
         Can no longer draw a pattern directly to the screen without
          claiming memory.
         No longer works on RISC OS 3.1.
         Finally calculates required memory for a drawfile properly.
         Complete rewrite of sprite handling code, which now uses a Wimp
          icon.
         This made the palette-swap bodge obsolete, so I removed it.
         Added interactive help on the menus.
         High accuracy values now just use MakeDraw's AutoCurve procedure
          instead of the previous control point farce.
         As a side-effect, odd accuracy values now work properly.
         Hole distance from edge of wheel can now be negative.
         Hole distance from centre can now be 0.
         Hole distance from centre is now writable.
         Added keyboard shortcuts to increment and decrement the current
          icon (invaluable).
         Added a load more shortcuts while I was at it.
         Tooth start positions for every wheel are now configurable.
         And can be negative.
         Start pos and end pos can also be negative (mainly intended for
          drawing sections of pattern which straddle 0).
         Line width in drawfile is now configurable.
         Out-of-memory errors now report how much.
         Overhauled out-of-date obey files.
         Now distributed with MakeDraw documentation (which it probably
          should have been in the first place).
         Removed 'Total cycles', 'Total rotations' and 'Plate start max',
          which are meaningless with more than two circles.
         'Auto update' continues its oscillation between the main menu and
          the dialogue box.
         Did the five-minute bugfix in version 1.22 properly.
         Uses a proper poll mask, instead of just 1.
         Robustified save boxes with respect to invalid filenames.
         Long list of improvements to window string handlers, which
          definitely won't overwrite validation strings any more.
         Clicking the 'Draw' button with unchanged configuration now just
          opens the window.
         Window size calculation now works for absolutely everything.
          Probably.
         StrongHelp manual now available in a text version.
         Quit using subpages, because StHlp2Txt can't cope with them.
         Doubtless more stuff that I forgot.
      ========================================================================

                                   Formalities
                                   ~~~~~~~~~~~

    Plotter code and most other code  Martin Bazley
    Some Wimp code     Martyn Fox
    MakeDraw library   Chris Dennis & C.K.Hall
    ResFind  Olaf Krumnow & Herbert zur Nedden

    Licence
    Contact

    http://www.starfighter.acornarcade.com/mysite/
    ==========================================================================

                                      Licence
                                      ~~~~~~~

      This program is free software: you can redistribute it and/or modify it
      under the terms of the GNU General Public License as published by the

                                                                        Page 9
      Free Software Foundation, either version 3 of the License, or (at your
      option) any later version.

      This program is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.

      You should have received a copy of the GNU General Public License along
      with this program.  If not, see http://www.gnu.org/licenses/.

      The Spirograph name and trademarks are held by Hasbro Inc.

      The application name Cogs has been officially registered with RISC OS
      Open Ltd.

      If you're going to review or mirror this program, I'd appreciate
      knowing about it!  (Especially if you're going to give it a good
      review. :-) )
      ========================================================================

                                      Contact
                                      ~~~~~~~

      martin@bazleyfamily.co.uk

      Martin Bazley
       Flat 8
        349 North End Road
         Fulham
          London
           SW6 1NN
            ENGLAND
      ========================================================================































                                                                       Page 10
                                C o n t e n t s
                                ~~~~~~~~~~~~~~~


                Cogs manual                                   1

                Introduction                                  1

                Quick guide                                   1

                Reference manual                              2
                  Terminology and principles                  2
                  The Choices window                          2
                    How to find the least common multiple     4
                  Keyboard shortcuts                          4
                  Foolproofing                                5
                  Saving options                              5

                Patterns to watch out for                     6

                A short guide to undocumented features        6

                Cogs version history                          7
                  Version 1.00 (2nd June 2008)                7
                  Version 1.10 (13th December 2008)           7
                  Version 1.20 (31st December 2008)           7
                  Version 1.21 (14th March 2009)              8
                  Version 1.22 (14th March 2010)              8
                  Version 2.00 (3rd January 2011)             8

                Formalities                                   9
                  Licence                                     9
                  Contact                                    10



















    +----------------------------------------------------------------------+
    |                                                                      |
    | This text file was converted from a StrongHelp manual on 3 Jan 2011  |
    |                                                                      |
    |             using !StHlp2Txt version 1.10 (8 June 2001)              |
    |                           by Chris Morison                           |
    |                                                                      |
    |               email: organizer@morison.net                           |
    |                 web: http://www.organizer.morison.net/               |
    |                                                                      |
    +----------------------------------------------------------------------+

                                                                       Page 11
