-SQRVIEW-MANUAL v1.02					     bsjr; 05/11/16
 ====================

1._INTRODUCTION
 --------------
 SQRview is a tool for viewing bitmaps like QL's _pic, _psa, _scr and _spr
 files of any colour mode and .bmp files from 1 bit to 24 bit modes.
 It can thus also be a handy tool for PE programmers to produce backgrounds and
 sprites with its many conversion and saving options.

 This version 1.02 adds JPEG, GIF and PNG to the list of image types, thanks to
 the fast machine code tools written by David Westbury.

 SQRview will only run on SMSQ/E 3 systems in High Colour mode.
 It is written in SBasic on a QPC2 system for mode 32 but most options will
 also be available in mode 16 or 33.
 Most conversions are done with machine code tools for maximum speed.

 Sprite modes are normally converted by WMAN2, including any RLE compression,
 so they can be viewed directly. In some special cases of RLE or Big sprites,
 it will be handled by SQRview to get direct access to the unpacked data.
 Most other images will first be converted to the PIC format in the Native mode
 before they can be viewed.
 The converted image can then be saved as '_pic' and often as '_spr' as well.
 When no conversion is done, saving may not be offered.

 The viewing area has a minimum size of 456x220 pixels. Smaller pictures will
 be shown centred, small sprites will be shown as Pointer sprites.
 Pictures can be almost any size, memory permitting.
 The viewing window will automatically adjust to the larger picture size.
 If the picture is still bigger then the SQRview menu will allow, pan & scroll
 options may be offered.

   The _txt version of this Manual is optimised for use in QD, hit Label (^F6)
   to select a chapter.
   The _doc version is also provided for use in Quill.


2._INSTALLATION
 --------------
 Apart from a recent SMSQ/E (now 3.27), this program also needs MENU_rext
 (7.66, or better 8.02+) and Qlib_run (3.36mod) to be present.
 These extensions are not included.
 The v1.01+ navigation option also relies on the DBas extension, as used by
 SUQCESS. When this is not present, quick navigation through the current
 directory is not available and each file must be selected individually.
 DBas is freeware and can be found on many QL-sites.
 A DBas_sys file (DATA_bin & DBAS_bin combined) is now added to this .zip but
 is also included in the .zip files for SUQCESS-2 and SUQCESS-1 on my site.
 Any other extensions it needs are built in.

 Unzip and make sure the above mentioned extensions are loaded.
 Copy SQRview to a directory of your choice and execute.
 It can also be executed with a picture file name on the job stack so you can
 configure FileInfo2 to call it on the picture extensions.


2.1_CONFIGURATION
 ----------------
 The program should run without any configuration unless you have renamed
 your devices, so for your convenience there are a few items that can be preset
 with Config or MenuConfig.

  1. The root directory - If left empty the HOME directory, the DATAD$ or
     PROGD$ default will be taken. (preset at 'win1_')

  2. The picture directory - Where you start to look for pictures to load.
     (preset at 'win1_Pic_')

  3. A temporary device or directory - For some GIF conversions extra temporary
     files need to be created, this is where. (preset at 'ram2_')
     These files will be deleted on every new image Load or on job exit.

     NOTE: This use of item 3 is slightly different from previous versions.
     (see also 5.2.1._ANIMATED_GIF /VERBOSE)

  4. A general temporary file name - Some conversions are done in reserved
     memory, others are done to this file. The name should include the
     directory but if not the program will append one.
     The default is 'win1_tmp_Cvt2Pic_sqv'.
     This file will be deleted when a new one is made or on leaving the job.

  5. The default Load extension - The picture type you want to start with.
     The default is '_pic'. If the program is called with a file name then the
     extension of the loaded file will be used instead.

  6. The minimum width in pixels for the SQRview window (e.g. 600).
     Leave it at zero for the minimum display width of 460.

  7. The minimum height in pixels for the SQRview window (e.g. 480).
     Leave it at zero for the minimum display height of 240.

  8. The maximum width in pixels for the SQRview window (e.g. 800).
     Leave it at zero for the maximum display width.

  9. The maximum height in pixels for the SQRview window (e.g. 600).
     Leave it at zero for the maximum display height.

 10. Use pan/scroll arrows - You can opt for No arrows, Always arrows or Ask
     each time an new image may need panning or scrolling.

 11. Use a chequered background - This will be shown if one of the image
     dimensions is smaller than the window size, otherwise it's an even grey.
     Again No, Always or Ask are the options here (See also F3-Commands).
     Setting this to 'No' on slower systems may speed things up.

 12. The System Palette to use.
     Zero is the default and 1, 2 or 3 are the other options.

 13. Make automatic use of the DBas engine.
     Yes (1) is the default, No (0) will ignore DBas even if present.

 14. The minimum delay for Animated GIFs.
     The default value is 1 for a delay of 20ms, up to 50 (1sec) is possible.
     On some systems it may seem frames are skipped. There you may benefit from
     a longer delay.
     (see also 5.2.1._ANIMATED_GIF /VERBOSE and 3.8_F3-Commands)


3._USING_SQRVIEW
 ---------------
 The menu is mainly taken up with the application window to show the picture.
 The small border space at the top holds the program name, the	filename of the
 loaded picture and some loose menu items.
 - MOVE button	(key: ^F4): The current picture name is also the Move item.
   This may also show the file number and total count of possible image files
   in the current directory.
   This item also acts as a progress bar on some of the more time consuming
   operations, or an occasional "wait" or "overwrite" prompt.
 - NAVIGATE (key N)ext, B)ack): The two hooks are only selectable if DBas can
   be used. These allow quick browsing of all images in the current directory.
 - F3 button (key F3): Some Commands for navigation, loading etc.
 - WAKE button	(key: ^F2): further right, to redraw the current screen.
 - SLEEP button (key: ^F1): the down arrow to the right.
 - QUIT button	(key: Esc): the red arrow at the far right.


3.1._LOADING_PICTURES
 When executed without a picture name you are presented with an empty window
 and a prompt to directly load a picture, or quit.
 When this first Load is invalid you can DO on the main window to open this
 prompt again.
 Whether a picture is showing or not, you can always HIT the red arrow and
 then OK to choose a new picture to load.

 A second prompt will select between PC or QL type images.
 This is mainly there to get you started on the right type of extension, eight
 QL types or eight PC types for the F4 option in File Selection.

 DOing F4/Ext in the File Selection window lets you pick another type, pick
 "No" if the wanted extension is not in the list.
 The last chosen type will be the new current default after a successful load.
 Further questions may need to be answered depending on the type of picture.

 The file is first checked for its validity and when all seems okay the file
 is loaded and converted if needed. Then the window is recalculated and
 redrawn with the new picture usually centred in it.
 If one of the picture dimensions is smaller then the minimum menu, a
 chequer-board background will be used (see Configuration 11).
 Loaded Pointer sprites can be moved around on a basic eight coloured grid.


3.2._PANNING_&_SCROLLING
 Pan & scroll bars will be shown when a picture is too big for the screen.
 Dragging these bars will move the picture in the viewing area.
 You can also opt for arrows, then you can hold down the left mouse button for
 a continuous move.
 If no arrows are present, HITting the picture near the edges will also move
 the picture, starting with 4 pixels at the time but this step increases with
 every HIT you make.
 If you have a scroll mouse, that is also recognised for scrolling.
 Lastly the Alt+arrow keys can be used to move the picture in the window.


3.3._TRIMMING
 When a picture fits the window, HITting the edges has a different meaning.
 Then you can move it one or four pixels left, right, up or down.
 The picture will move in the opposite direction and whatever falls outside
 the original picture boundary can be trimmed off at saving time.
 A HIT on Wake will undo any Trim settings and restore the original picture.


3.3.1._MORE_TRIMMING
 From v1.02 it is also possible to trim a picture that doesn't fit the current
 window. This option is only available if no conversion has been done, so the
 file must already be in the current Native mode.
 A DO will open the Status window and then there will be a "Trim" option.
 You must specify how many pixels should be shaved of the Top, Left, Right or
 Bottom, in that order. Then a box will be drawn to show the new size and a
 Save menu will be presented for PIC or SCR.

   NOTE 1: If only a few pixels are specified it's possible the Trim-box is not
   visible but the new size will always be shown in the Save prompt.

   NOTE 2: Trimming is not available when a Native PIC is Stretched or Reduced
   in height or for sprites. Save that PIC first and trim after reloading.

   NOTE 3: When you Escape from the Save prompt the trim values are lost and
   any pan or scroll action or a Wake will also remove the Trim-box.


3.4._STATUS
 A DO on the main window shows the picture status: file name, type, mode & size
 etc., and if conversion has taken place, some viewing statistics.
 From here you can also "Save" a converted picture or "Trim" a big Native one.
 If you choose "Load" here, you can select a new picture or leave the program.
 (See 6._STATUS_WINDOW)

3.5._SAVING
 Saving should be done from the Status menu before a new picture is loaded.
 When saving is not offered, using the Wake option may also set the Save flag.
 Beware that saving is NOT offered each time you load a new image, this is done
 deliberately to allow for a quicker browsing sequence.

   Here is a summary of some of the save options that may be presented,
   depending on the conversion that has taken place:
   (See below "4._BITMAP-TYPES in detail" for more.)

   - BMP, all bit modes to PIC, can be saved as Native mode PIC or SPR.
   - BMP 8 or 24 bit to mode 16 SPR can be saved as mode 16 SPR or PIC.
   - BMP 8 or 24 bit to mode 64 SPR can be saved as mode 64 SPR or mode 16, 32
     & 33 PIC or SPR, regardless of the actual Native mode.

   - PIC & SCR mode 4 or 8 can be saved as original mode SPR.
   - PIC & SCR mode 4 to 33 can be saved as Native mode PIC or SPR.
   - PIC & SCR mode 16 to 33 can be saved as Native mode SPR with RLE.
   - PIC, big Native ones can be Trimmed and saved as PIC or SCR.

   - SPR, mode 4 to 33 can be saved as Native- and some as original mode PIC.
   - SPR, mode 64 can be saved as mode 16, 32 or 33 PIC or SPR.
   - RLE compressed SPRs can now be saved in the original mode as PIC or
     uncompressed SPR, or in Native mode by reading the colours from screen
     memory, which may take a little longer.
   - Chained or Extended SPRs can be selected individually and extracted as
     original SPR from the chain, without changes.

   - JPEG, GIF or PNG can be saved in the QL Native mode as PIC or SPR.
     Animated GIFs can only be saved as individual frames to PIC or SPR.


3.6._WAKE
 A HIT on the Wake icon will refresh the display.
 The former DO option to change backgrounds, has been moved to F3-Commands.
 Wake is disabled when the current image is a Pointer sprite.


3.7._NAVIGATION
 Hitting the greater/less items on the top will find the next or previous file
 in the current directory and show it, but only if it is recognised as a valid
 picture, when not, an error report is given. Hit it again to try the next.
 Some of the normal load options will then be skipped and defaults used.

   You can also use some character- or arrow keys:
   "N" - for the Next filename in the sorted list (or Shift-Right)
   "B" - to go Back in the list of filenames	  (or Shift-Left)
   "F" - for the First filename in the list	  (or Shift-Up)
   "L" - for the Last filename in the list	  (or Shift-Down)

 Next to the filename in the top you will then also see the total number of
 files and the position of the current file in that list.

   NOTE 1: Sub-directories, executable and relocatable file types are filtered
   from this list. But I have come across valid image types that had the type
   flag set wrong so they would not show up in this list.
   You can still view these by selecting them directly through "Load" where
   files can be selected on the extension.

   NOTE 2: If a converted image is saved to the current directory, the list is
   read anew but if you change anything there directly, outside SQRview, this
   makes the list invalid. If a 'Next' or 'Back' filename produces an error,
   the directory database is renewed but the current file reference may be
   false. The best way is to do a new Load.

   NOTE 3: A special key - Ctrl-Alt-Down - can be used to switch OFF
   Navigation. This way you can unlock a WIN drive if more than one QPC2 or
   SMSQmulator is running because the open DBas channel prevents sharing
   devices.
   Use the same keys to set DBas ON again, a new Load is then needed to create
   a directory database before Navigation works.


3.8._F3_COMMANDS
   Previous versions used menu itmes with double functions; different actions
   if HIT or DO was used. But new actions could not be added this way so now
   there is a Commands menu that is more future proof.
   The current F3 options are:
     0. To First picture in the list	 (or key "F" or Shift-Up)
     1. To Last picture in the list	 (or key "L" or Shift-Down)
     2. Load new picture		 (or DO image and click Load there))
     3. View system sprite		 (was DO on the Quit button)
     4. Navigate directory On or Off	 (or key Ctrl-Alt-Down)
     5. Change background colour & type  (was DO on Wake button)
	A choice of 9 colours or grey, and chequered or solid
	(see Configuration 11).
     6. Change Animated Gif delay	 (new option)
     7. Delete current source image	 (new option)

   Some options may be switched off if not relevant for the current picture.


4._BITMAP_TYPES IN MORE DETAIL
 --------------

4.1._BMP_24,_16, 8, 4, 2 & 1 bit -
   These can be loaded directly as a PIC in the Native mode.
   Then they can also be saved as Native _pic or _spr files.

 BMP 24 uses 3 bytes per pixel, BMP 16 uses 2 bytes per pixel which are
 identical to the mode 32 colour bytes for QPC, QXL & SMSQmulator.
 BMP 8, 4, 2 & 1 all use a palette of 4 bytes per colour but the fourth byte is
 always ignored. This gives a maximum of 256, 16, 4 or 2 colours respectively.

   NOTE 1: 1 bit is mostly used for monochrome images but it is perfectly
   possible to use other colours than black & white. Some PC viewers may XOR
   these two colours but SQRview will translate them individually.

   NOTE 2: I have not been able to test the 2 bit type as none of the picture
   software on my PC's was able to produce it.


4.1.1._BMP_24_&_8 bit -
   These can be converted directly to sprites in mode 16 or 64.

 The mode 64 sprite is normally made with an alpha channel for compactness.
 But both can also be saved as Solid, without mask, which is even smaller.

 For the alpha mask you can also give coordinates for a pixel colour, then all
 pixels of this colour will be made transparent. Enter the coordinates as a
 string of 2 numbers separated by a space, point or comma.

   NOTE: The program can also help you find the coordinates for transparency.
   First load as sprite without transparency, then move the pointer to the
   colour you want to select. When you DO at that point the pointer position is
   remembered and also shown in the STATUS title.
   When you hit "Load" there and reload the BMP as sprite, these coordinates
   are suggested for transparency, just confirm to make this colour disappear.

 These sprites can also be saved as _pic or _spr files.
 Mode 16 will be in that same mode but as _spr it can also be RLE compressed.
 Mode 64 can also be saved as original _spr and be RLE compressed.
 Saving it as PIC or SPR can be in 3 Native colour modes (see SPR 64).

   NOTE 1: Any transparency is lost when you save this sprite as a _pic file.

   NOTE 2: There may be a significant colour difference between a mode 16
   sprite made from a BMP 24 or 8 and one converted from a mode 64 sprite, due
   to differences in algorithms used. Try it out to see which suits best.

   NOTE 3: Mode 64 cannot be mode converted and compressed at the same time.
   To do this make the mode conversion first, reload and RLE compress next.


4.1.2._ICO -
   Sometimes PC .ico files are just renamed .bmp files so these can be loaded
   if the header analysis confirms this.


4.2._PIC_&_PSA - Mode 4, 8, 16, 32 or 33 -
   These can all be loaded and will be converted to the Native mode if needed.
   Then they can be saved as Native _pic or _spr files.


4.2.1._SCR -
   The same modes can be loaded and saved as for PIC files.

 Because the size for _scr files cannot be read from the data, the program
 tries to make a guess, which has to be confirmed or adjusted.
 One clue to the dimensions is the file size: 32768 bytes is most likely a
 standard 512x256 screen in mode 4 or 8. So on that basis suggestions are made
 and you can confirm or change these.
 Another way is to look at the filename, sometimes the size is added to it
 like 'name256x128_scr'. The name is checked for this and then size and mode
 values may only need confirmation.

   NOTE: Normally the SCR mode can be calculated when the size is known but
   when an invalid mode is found this way, the next lower mode is suggested.
   When the image looks wrong, the given size may not be correct.
   As long as the total sum is not greater than the file length something will
   be shown but it may be distorted.

 When saving a PIC or SCR as a _spr you can also set an alpha value. Enter 0
 for a Solid sprite (no mask) or 1 for a minimum, to 255 for a maximum opacity
 value. This value will be set for all pixels.

   NOTE: When saving a PIC or SCR as _spr any Trim settings are ignored.
   For a trimmed sprite you need to save it as trimmed _pic first and reload.


4.2.2._PIC_RATIO
   For PIC, PSA or SCR images you can change the X:Y pixel ratio to restore
   circles and squares.
   This option is only available with a direct Load.

 The X:Y ratio on the original QL is 2:1, but when viewed on a TV screen pixels
 are stretched to fit a standard 4:3 display.
 QPC2 and QXL systems use square pixels, then a picture may look too flat.
 Therefore there is an option to Stretch or Reduce the picture height.
 Stretching the height can be done to a 3:2 or 4:3 ratio.
 Reducing the height can be done to 3/4 or 2/3 of the original.

 Pictures made on an original QL or a Qx0 machine may benefit from stretching
 when viewed on a mode 32 system or Aurora, while on mode 33 systems the reduce
 option may be helpful to adjust the ratio for mode 32 pictures.

 This stretching or reducing is done while the picture is copied to the screen,
 so it can be saved in the original or the transformed size.

   NOTE 1: Stretched or Reduced images can only be saved as _pic files.
   If you want such a transformed sprite you have to save it first and reload.

   NOTE 2: Some QL tools for extracting sections of the screen may add padding
   to each line, for High mode _pic files as well, while this is only needed
   for sprites. That could crash SQRview before but this has been fixed in
   version 1.01. The size in Status may then show this as an extra greater
   pixel width in brackets.
   (See also THE OTHERS - SCRSAV)


4.3._SPR - mode 16, 32, 33 & 64 -
   Sprites can range from small Pointer sprites up to the maximum that will fit
   in the window or beyond. Normally sprites cannot be scrolled or panned.
   If the SPR is a collection of Chained or Extended sprites then the name on
   top will be appended with a '%' sign.

 The same option to view sprites produced directly from BMP files, is also used
 to load and view original sprites.
 In that case the program doesn't always need to do any mode conversion before
 viewing because this can be left to WMAN2 itself.
 Extra conversions may be done when saving the sprite as _pic files.

 Depending on the size it will be shown as the Pointer or as a Static sprite.
 You can save these as _pic files from the original sprites.
 For sprites that used RLE compression, see below: "SPR with RLE".

 For a Save as PIC any alpha setting is obviously ignored and the original
 background pixel colour is revealed.
 For a SPR Save any existing alpha mask is copied, a normal mask is replaced
 with a fixed alpha mask or the mask can be dropped completely (Solid).

   NOTE 1: If alpha was set a small sprite can also be saved as PIC in Native
   mode from screen memory for which you can select a different background.
   This makes it possible to recolour those pixels that have transparency set,
   which are often black. Remember that the save area is always rectangular, so
   this is only relevant if any background shines through.

   NOTE 2: Up to v3.13 there is a bug in SMSQ/E for QXL, that can make sprites
   with a Solid mask look ugly. A mask is still read, but from beyond the
   sprite in memory! Change the background to an even black for a proper view.
   (Better update to SMSQ/E 3.15+)

   NOTE 3: The QDT desktop uses _ICONs that look and behave like sprites but
   their format is not standard. SQRview recognises this and rejects them.


4.3.1._SPR_mode_64 -
   This mode doesn't exist in PIC format so mode conversion is always needed
   for a PIC Save.

 You can choose which mode to make; 16, 32 or 33. These modes can also be saved
 as _spr files, this will normally create an alpha mask: the original, a new
 one or no mask (Solid) if there wasn't one.


4.3.2._SPR_with_RLE -
   Normally these are handled by WMAN2, invisible to the program, but from
   version 1.01 SQRview also has its own routines for RLE compression.

 Pointer sprites will be shown in the normal way. Only when you want to save
 this as a PIC or as normal sprite will these be unpacked by SQRview.
 Mode 16 to 33 can be saved in their original mode.
 Mode 64 can be saved in modes 16 to 33, regardless of the Native mode.

 Larger sprites will be shown as Static sprite and then the internal RLE
 routine is used before viewing, while WMAN2 is still used for the Native
 colour conversion. The same save options apply as for Pointer sprites.


4.3.3._SPR_without_RLE -
   Normal high mode SPR and also PIC files can now be saved as RLE compressed
   sprites. This can be done with an alpha mask or no mask (Solid).

 That will only be useful of course if the packed sprite turns out smaller than
 the original. Photographic images are usually bad candidates for this type of
 compression - 10 to 30% gain - unlike JPG or GIF, so give it a try to see if
 the reduction in size is worthwhile.

   NOTE: When there is no size reduction at all the packing routine will
   abort processing and the pattern or mask will be saved as normal. So it's
   possible that the pattern is not RLE while the mask is, or vise versa.
   Watch the "done" prompt at the end, or check Status after reloading.


4.3.4._SPR,_Very_Big -
   Marcel Kilgus has made it possible to create very big sprites as a new
   picture format with an alpha or Solid mask.

 The main problem is that the sprite must always fit inside the viewing area.
 If a sprite is too big for the maximum display it can now immediately be
 converted to a Native PIC and thus seen with scroll and pan options.
 The default is to show this PIC conversion. That will then of course ignore
 any mask settings. This default is always used in navigation.
 The original sprite will then be dumped from memory.
 The Native PIC can then be saved.

 You can also choose to show as sprite and run the risk of not seeing anything
 but a size-error sprite. If the width fits in the maximum window you can at
 least see as much as will fit in the window from the top.
 This partly visible - or the invisible sprite can still be saved but then in
 the original mode as PIC or RLE packed SPR if it wasn't or unpacked if it was.


4.3.5._SPR,_EXTENDED -
   These will initially only show the first 'available' status. The others are:
   available & current, selected, selected & current and unavailable.
   Each status can be seen and saved as a single sprite.
   (see also QL Today v8i1p47 'New functionalities in SMSQ/E part 2')

 A DO on the main window will show info on the whole file.
 A HIT will beep once and then step through the various statuses from 1 to 5
 with each HIT.
 A DO then shows info on this single sprite, which may also be extracted and
 saved from here.
 "OK" will just close this Info, "Next" shows the next sprite in the list.
 A HIT after the last one beeps again, signalling you're out of this loop.

   NOTE 1: Not always are all 5 sprites present in the file, one sprite may be
   used for more than one status. The info window will then show the real
   sprite in brackets. So you may not need to save all 5 separately.

   NOTE 2: I have come across Extended sprites that were sharing patterns or
   masks. These work perfectly under WMAN2 but cannot be extracted for now
   because not all elements can be retraced and collected by SQRview.


4.3.6._SPR,_CHAINED_&_DYNAMIC -
   These sprites come in two versions. It is a collection of sprites that may
   or may not be linked. Normally only the first sprite is seen.

 When a timer value is set, it's called a DYNAMIC sprite and then each sprite
 is shown in sequence using the timer value set for each one.
 This was originally intended for Pointer sprites and they will automatically
 be shown as Dynamic if valid timer values are found.
 SQRview also accepts Static Dynamic ones (see NOTE 4).

 A DO will again show info on the whole file.
 A HIT stops any animation and allows stepping through the single sprites from
 first to last. A DO here then shows info only on this sprite, which can also
 be extracted and saved from here. "OK" and "Next" are the other options.
 When there are more than 9 sprites in the chain you can Choose one and
 continue the loop from there.

   NOTE 1: A Chained sprite may itself contain Extended sprites. To get at the
   individual statuses you can extract the Extended SPR as a whole first and
   reload this for further investigation.

   NOTE 2: If a mode 4 or 8 sprite is chained with and points to a high mode
   sprite, you may not see this low mode at first because WMAN2 automatically
   jumps to the high mode, while Status reports it's a low mode SPR.
   A HIT will now step through all the modes correctly. You can then extract
   each low or high mode from its own Status menu with "Save".

   NOTE 3: If sprites are chained without having the pointers set to the next
   sprite, only the first sprite will be visible and the number of sprites can
   not be determined. The Status window will show only 2 different lengths.

   NOTE 4: If timers are set for a non Pointer SPR, animation is not automatic
   but if you step through each sprite with HIT then the last HIT may show all
   sprites in timed sequence continuously, until you click DO or hit the
   'Escape' or 'Q' key. (Try SWxmpl_spr)


4.3.7._SPR_&_PSA,_QL_mode_4_&_8 -
   QL mode SPRs can be shown and saved as pic files.
   If the SPR is a collection of Chained or Dynamic sprites then the name on
   top will be appended with a '%' sign.

 Sprites in these modes may look wider to the right when saved to a _pic
 because each line is padded to a multiple of 4 bytes and some pixels may have
 been set to be transparent.
 Therefore these can be saved in the original mode as _psa files which have a
 special header, holding the original width. This is recognised when such a
 _psa is loaded and a HIT in the viewing area will then toggle between this
 original and the full width.
 The Status window shows this original width next to the size label as [xx].

   NOTE 1: This use of the extra 4 PSA header bytes is exclusive to SQRview.

   NOTE 2: From version 1.01 SQRview has better support for padded SPR or PIC
   files in all colour modes.
   This PSA save option is now less relevant but still present.


4.3.8._SYSTEM_SPRITES -
   These can also be shown as Pointer sprite but cannot be saved!
   You can select them directly by number from the F3-Commands menu: enter a
   number (0-37) and the sprite will be read from the system.

 This could also be a minimal _spr file of 4 bytes where the first 2 bytes hold
 the sprite mode flag (=0) and the number for one of the current 38 system
 sprites.
 These SPRs are handled by WMAN2 internally, but header info is available about
 size, RLE, Extended or Dynamic. The file size in the Status info will be
 calculated only for the first of any chained sprites and may not be accurate
 especially if RLE compression was used, so Save is NOT an option.
 (See also QL Today v8i3p23 for a list of valid numbers.)


5._COMPRESSED_PC_TYPES
 ---------------------
   These are a new addition in v1.02 thanks to the tools written by D.Westbury.
   To minimize memory usage the fast M68K machine code converts the original
   file directly to a temporary PIC file for the Native mode, which will then
   be loaded directly by SQRview.

   NOTE: All these compressed modes support many options and the tools used
   by SQRview cope with most of them but not all. Hopefully SQRview will
   correctly report the options that are not supported.


5.1._JPEG_24,_8 bit
 This format is used by almost any digital camera these days and can reach
 high levels of compression but for any Viewer the uncompressed size matters.
 JPGs from my 10 Megapixel camera will produce mode 32 PIC files up to 20MiB
 and unpacking these JPGs may still take up to 50 seconds on my QPC2. So while
 the "Wait.." prompt is there, have patience and enough memory available.

 By default JPGs are converted to full colour (24 bit) or black & white (8 bit)
 but when loaded directly you can also choose black & white or sepia regardless
 of the original colour mode.

 This format also may include Exif data, detailed info on how, when or where
 this JPEG was made. SQRview does not access that info but will report in the
 Status menu under 'Header' if the 'Exif' marker was found, else it will
 simply say 'JPEG'.


5.2._GIF_8 bit
 This format was introduced for use on web pages. To reduce transfer times the
 number of colours is indexed with an 8 bit value to a maximum of 256 but as
 for BMP lesser bit modes are also possible. More compression is added to that.
 Usually these images are not as large as JPGs so they most likely fit the
 screen and then conversion can still be quite fast.

 This format also supports an alpha channel like SPRs but that is not an option
 in the PIC format used by SQRview so the original background is shown by
 default.
 When loaded individually you can choose to use a white background instead.
 The Status menu will also tell you if alpha was found.


5.2.1._ANIMATED_GIF
 This is another option that is detected but not shown automatically and you
 can choose to load any frame but the first is always the default.
 To quickly identify such files, a "%" character is printed after the filename.
 A HIT in the centre opens a menu from where you can "Play" the animation once,
 "Reset" to the first or pick another "Frame".
 A DO opens the Status menu which also tells you how many frames there are and
 which is current, the total playing time in seconds and the time set for this
 frame in brackets.
 The save option will save only that frame (Try SWxmpl.gif).

 VERBOSE
 there are many ways to reduce the number of bytes used for a GIF, like partial
 transparency in Animated Gif frames. So if some frames look weird, this may be
 one of those occasions.
 If you play the GIF once and the alpha marker was found, the "Frame" option
 will be changed to "Verbose" for an improved animation.
 When you choose this option all frames will be made into a series of numbered
 PICs first and then played continuously until the 'Q', 'Esc' or 'Enter' key is
 hit.
 A new menu then allows you to "Step" through each frame and "Save" that.
 An "Esc" here resets the View window but a new HIT will replay the GIF.

   NOTE 1: BEWARE, this Verbose option may need a lot of memory or disk space
   because each frame is converted in full. A simple 12 frame animation of
   150x150 pixels in mode 32 will need room for 540KiB. One of my GIF examples,
   which itself is only 330KiB, needs 15MiB for all of its 91 frames of
   290x290 pixels.
   The default temporary disk (cfg item 3) is tested first and the given
   Temporary PIC device next (cfg item 4), if needed. If no space is found the
   action is aborted.
   All frames will be automatically deleted before a new image is loaded.

   NOTE 2: The frame times as shown in Status are read and calculated from the
   original file and used to delay each frame. But that's only an indication.
   The time the program needs to do its thing is added to that.
   In normal Play each frame is converted and shown separately but in Verbose
   Play all frames are converted first and thus the show may be more accurate.
   While frames can have delays set as low as 10ms, SQRview uses a minimum of
   20ms. Also Viewers and Browsers on 'non QL' platforms are known to use these
   timings loosly.
   You can also change the minimal timing from the F3-Commands menu.
   (see 3.8 F3- and also 2.1 CONFIGURATION)


5.3._PNG_24_&_8 bit
 This type was developed as a non-patented alternative for GIF.
 It uses lossless image compression and is widely used on the internet.
 Just like BMP, True-colour and various indexed modes are supported.
 An Alpha channel can be used which is reported in Status but ignored by
 SQRview. To see how any transparency is used I suggest you use PNGconv to
 convert it to a sprite first and open that in SQRview.


6._STATUS_WINDOW
 ---------------
 This is opened when you DO on an image and shows information on that image.

 type	: The image type as indicated by the extension, plus the colour mode.
	  For special sprites this will be followed by:
	  [xtn:n] - for Extended,  [dna:n] - for Dynamic,
	  [chn:n] - for Chained,   [sys:n] - for a System SPR.
	  Then n is the number of sprites in the file or System SPR number.
 file	: The filename without directory or extension.
 device : The device & directory part.
 date	: The date of the original image file.
 size	: The image dimensions, width by height.
	  If high mode padding was used, it's followed by the maximum pixels
	  that would fit. Also if excessive padding was used for low modes.
	  (See also: THE OTHERS - SCRSAV)
 origin : For SPR or GIF only, the origin settings.
 length : The file length, this may be followed by another length if the
	  calculated length differs from this file length.
	  For SPRs this calculated length can be greater when RLE was used but
	  smaller if more sprites are chained. Then no error is reported.
	  If trimming was used that's also indicated here with [trim].
 header : For BMP or SPR files only, the header length.
	- For BMPs this may be followed by a second length which includes the
	  palette or mask space.
	- For SPRs this may be followed by the compression type for pattern
	  and mask. If this ends in 'Solid' then the sprite has no mask.
	  If no Alpha or Solid is mentioned the SPR has a standard mask.
	- For JPEG, GIF or PNG there is no single fixed header so this will
	  only reflect the ID strings like 'JPEG', 'Exif', GIF87a','PNG' etc.
 frame	: For Animated GIF only. Gives current and total frames plus total
	  "time" and delay for this frame in seconds.
 alpha	: Only for SPR, GIF or PNG, 'Yes' if an alpha mask is found and may be
	  followed by the alpha value found, usually at the top-left position.

 If the image was converted in some way, more data may follow:

 view as: The viewing type and colour mode, usually Native PIC or SPR.
 length : The length of the converted PIC or SPR file. IF Stretch or Reduce was
	  used this is the standard length indicated by "[std]".
 stretch or reduce : If used, the length followed by the type and line count.
 header : the SPR header length if it was directly converted from a BMP,
	  followed by 'Solid' if their is no mask made.
 alpha	: 'Yes' if this mask type was set, and the value as before.

 Some conversions can produce a picture that is too big for the maximum menu
 then you also see this:

 menu aw: This is the size of the viewing area, and the offsets top-left.

 The menu title may show the pointer coordinates when you did the DO on a BMP
 source image and converted it to a SPR file (see BITMAP TYPES, BMP24/8).


6.1_STATUS_OPTIONS
 OK   - just closes the Status window.

 LOAD - can be used to load a new picture or Quit the program.
	A new Load will also renew the directory list.

 SAVE - choose this to save a transformed picture.
 Before Loading a new picture, any converted image can be saved from here only.
 Before you Quit the program, saving can also be offered.

 TRIM - is a new option for v1.02 and is only available here if a Native PIC is
 loaded, so no conversion has been done, and if it's bigger than the maximum
 window allows.
 You can specify exactly how many pixels or lines should be trimmed of the
 PIC on each side, followed by a "Save as PIC or SCR". Handy for the BGIMAGE
 command. (See also 3.3.1._MORE_TRIMMING)


7._LIMITATIONS
 -------------
7.1._MEMORY
 If memory is insufficient to hold the original and the converted image, the
 current loading action will be aborted. A full screen picture on my QPC2 is
 often 2 to 3MiB, so then 5 to 6MiB needs to be free.
 The current limit for BMP, PIC or SCR sizes is set at 4096x3072 (12-36MiB!).
 The SPR limit is set at 2048x1536, if you happen to have such a big screen.
 My current biggest test sprite is 1600x1200 (3.8MiB), too big for my display!

 A BMP to SPR conversion in mode 64 takes at least 3 times the size of the BMP
 file from your memory, so it's best to save any open files before attempting
 this if memory is low.

   NOTE 1: IF such a sprite's width fits the window but the height is too big,
   then it can be shown from the top, truncated at the bottom.
   Sprites that are too big for the maximum window in both dimensions can be
   seen as PIC directly but only if loaded as sprite. This doesn't work for
   the BMP-2-SPR option. A warning is given and an error sprite shown instead.

   NOTE 2: If memory is limited it may happen that the initial conversion is
   done but nothing is showing, WMAN2 may still abort lacking free space.
   In these cases, if a DO gives the Status window, you may still be able to
   save the whole image and it can then be seen after loading this.

 As pictures can be very memory hungry, a test is done before each allocation.
 Previously claimed memory is freed at the last moment before loading but if
 the new image and its converted copy need too much memory the action may still
 be aborted.
 A default value of 200K bytes is set to be free at all times.
 If memory is low the File Select window will also be limited to 20 or 10 lines
 to save some space.


7.2._VALIDATION
 I have tried to make sure that only valid image files can be loaded and all
 others will be rejected. The first check is made on the basis of the extension
 and then the header is checked for any ID and sensible values.

 Valid pictures must have one of the following extensions:
 QL types
 with headers - PIC, PSA or SPR
 no headers   - SCR, MODE, EGA, VGA, SVGA, XVGA or XGA
		If this extension is followed by a number (scr4, mode8) then
		that is suggested as mode for that screen file.
 PC types     - BMP, ICO, JPEG, JPG, GIF, PNG

 Normally if SQRview rejects an image for some reason, or you abort a loading
 action yourself, you are left with the current image intact.
 Sprites are an exception. Because these are loaded before the header can be
 analysed, the original image is dumped first to limit memory use.
 When selected with Navigation, a Wake may reload the last image.
 PC compressed types may still produce an error on conversion, even when
 initially found valid. Then too a previous image is gone and a new Load is
 needed.


7.3._MENU_TIME-OUT
 The Status windows and some others use the time-out option only available in
 MENU_rext 8.01+, older versions will ignore this setting and you must click on
 the window to clear it.


7.4._OVERRIDING_DEFAULTS
 Most defaults can be changed by configuration but you can also override some
 and set a few others with the CMD string:
   %C:nnn - sets a new minimum width to nnn   (0= minimum 460)
   %R:nnn - sets a new minimum height to nnn  (0= minimum 240)
   %W:nnn - sets a new maximum width to nnn   (>460 or 0= max)
   %H:nnn - sets a new maximum height to nnn  (>240 or 0= max)
   %T:nnn - sets a new time-out for the pop-up menus in 20ms (500 = 10s)
   %M:nnn - sets a free memory limit in KiBytes (100+) or MiBytes (1 to 9),
	    other values default to a minimum of 100KiB.
	    Note this can then be less than the normal default of 200KiB.
   %P:n   - sets a new System Palette value (0-3).
   %K:nn  - sets a new maximum for Chained SPRs (default = 20)
	    If you really need to see a longer chain, change this here.

   %A%	  - will set arrows if unset, or unset if set by Config.
   %D%	  - will toggle the 'ignore DBas if present' flag.
	    This was added because when testing SQRview in another QPC2 on the
	    same machine, the device was locked by DBas and could no longer be
	    shared by the first QPC2.

 These flags can be combined and also with a filename, then this name must be
 preceded by a backslash and entered as last parameter.
   e.g. ex dev_SQRview_obj; "%W:800 %H:600"
	ex dev_SQRview_obj; "%P:2 \dev_image_pic"
	ex dev_SQRview_obj; "dev_image_pic"  (no backslash here!)


7.5._VERSION_1.02
 SQRview is tested with SMSQ/E 3.16/3.26 on QPC2, QXL, Aurora and SMSQmulator.
 It was tested on all supported image types I could find on my systems.
 There were a few BMPs that did produce a picture on my PC but did not conform
 to any BMP standard I know of and they are thus rejected by SQRview.
 If any problematic PC type image does work on the PC side, you can try to
 resave it under a new name or with minor changes and see if that will open in
 SQRview.

 If you have some pictures that still produce errors but shouldn't, or worse
 crash the program, please let me know.

   IMPORTANT: This program is freeware.
   No guarantees whatsoever are given. Use it at your own risk.
   Please report any errors in detail to the address below.


8.1._ACKNOWLEDGEMENT
 -------------------
 This program was written with QD, in SBASIC with the help of EasyPTR 4 and
 compiled with Q-Liberator through BasicLinker, so it needs Qlib_run.
 Various toolkits were used, I thank the many authors.

 SQRview relies on MENU_rext from Jochen Merz for all of its sub-menus.

 It includes some code from the DIY Toolkit by Simon Goodwin.

 Some system sprites from Marcel Kilgus were also included in the menu code.

 Getting the info on system sprites is made possible with a function written by
 Per Witte and is copyright (c) pjwitte 2004.

 Part of this software incorporates software that is copyright (c) W. Lenerz
 2002.
 Wolfgang Lenerz has written the tool used for direct BMP to SPR conversions,
 including the 'colour to alpha' option.
 An older version of his tool BMPCVT, as used in QColour and early versions of
 QCoCo to produce nice menu backgrounds, was also used for early testing.

 Dilwyn Jones provided the tool for the SCR and PIC to PIC mode conversion.
 This is copyright (c) Dilwyn Jones 2006.

 The latest addition supporting JPEG, GIF & PNG was made possible with new
 functions written by David Westbury.
 It's freeware and copyright (c) D. Westbury 2016

 The tools used for BMP to PIC and SPR64 to PIC colour conversion are my own
 first attempt at writing machine code. This was greatly helped by studying
 the above mentioned tools and then that was followed up by writing the RLE
 packing and unpacking routines.
 These tools, this program and its documents are copyright (c) BSJR 2012-2016.

 The first focus of SQRview was more to act as a quick viewer for all kinds of
 bitmap pictures with the save options for the converted image as a side effect
 rather then the goal. More and more options were added along the way, that's
 why it takes so long to complete and it's still growing.
 SQRview started live as a small test program, after a discussion on the
 QL-Users list in June 2009 on 'how to make a scrollable menu for QL-screens
 with EasyPTR'. Then it got a bit out of hand.


8.2._THE_OTHERS
 --------------
 Most of these freeware programs were used in testing SQRview, to produce
 examples or to compare results.

 BMP2SPRT - by Wolfgang Lenerz can take 8 or 24 bit BMP files and convert these
 to mode 16 or 64 sprites but it can also be used to create Chained or Extended
 sprites as binary and assembler listings.

 BMP - by Dilwyn Jones converts 24 bit BMP files to QL PIC, PSA, SCR, DP2 or
 DP3 formats. QL formats can be changed in the same mode or modes changed in
 the same format. All these formats can also simply be viewed.

 Photon - by David Westbury is a viewer which does JPEG (GIF & PNG soon) and
 works on any QL platform in all modes.

 PhotoQL - by Roberto Porro is another free viewer that can be used for BMP
 bitmaps but it has no save option and like some of the earlier WL_BMPCVT
 commands it does not always cope well with odd pixel values and doesn't do all
 bit modes.
 However it can do several compressed formats like PNG, JPEG, GIF or TIFF and
 tries to resize if necessary to fit the display.

 SPRV & MSPRV - by Per Witte are two programs to view sprites, whole pages of
 them in the case of MSPRV. SPRV will also show statistics on single sprites.
 The latest version SprvAPM was made to be called from EasyPTR's AppMan4.

 EDDICON - by Duncan Neithercut is a freeware sprite editor that can load or
 create small BMP24 images, edit colours and alpha masks and save sprites in
 mode 64. SQRview can now be used to convert these to the more compact modes.

 SPRTED - by Jrme Grimbert is another free GD2 sprite editor for modes 4 to
 33. It can read PICs for patterns, pick binaries from memory and save as _asm.

 PMOVE - by George Gwilt is part of a freeware package that can manipulate PIC
 or PSA files in mode 16 to 33 (not 4 or 8). It has resize and crop options.

 PNGconv - by Marcel Kilgus is a useful tool running under Windows, to create
 sprites from PNG files in many forms and used for many of my test examples.

 SMSQESprites - by Wolfgang Lenerz is a Java program, so it doesn't run on a
 QL platform, which can convert GIF, BMP, PNG, TIFF or JPEG files to sprites
 with a very nice mirror effect.

 SCRSAV - is part of EasyPTR and can be used to snatch sections of a QL screen.
 QSnap	- is part of QDesign and does the same but only mode 4 or 8.
 GrabIT - by Phil Jones is another option for screen snatching.
 They all use x-line padding for all modes, sometimes more than needed and
 High Colour PICs don't need it at all but this is now recognised by SQRview.


 Happy Viewing.
 Bob Spelten JR, 2016

 <szx83@upcmail.nl>
 <http://members.upc.nl/b.spelten/ql/>
