+----------------------------------------------------------------------------+
|                                                                            |
| BLS.COM v3.0A User Manual                                                  |
|                                                                            |
| Copyright SEIGA (HOR-NET/PP-NET) Jun.1993                                  |
|                                                                            |
| Enhancement patch (C) FRS Jan.2023                                         |
|                                                                            |
+----------------------------------------------------------------------------+

1) DESCRIPTION

This is a multi-format image viewer application for the MSX-DOS, that features:

- A simple built-in file manager
- A direct mode to view files from the command line, without having to open
  the built-in file manager
- Support for multiple image formats:
  - MSX BLOAD image format (.SCx): The well-known MSX-BASIC image format that
    require no introductions. The .PIC files saved by Philips Video Graphics
    and Matsushita Video Graphics will be automatically recognized as .SC8
    by their header. But keep in mind that any mentions ahead in this document
    of a PIC format will be referring to the Yanagisawa's PIC, that's a very
    different file format.
  - MSX Interlaced BLOAD images (.SCx+.S1x files, optionally .S0x+.S1x): dual
    file BLOAD image used to display with interlace, for 424 lines of
    resolution
  - Graph Saurus screen images (.SRx+.PLx / .SRI+.PL7). Another very popular
    MSX image format that, when not compressed or interlaced, is just a
    variation of the BLOAD image format with an external palette file
    containing 8 independent 16-color palettes. BLS3 now also supports the
    compressed and interlaced .SRx variations.
  - MSX2 COPY images (.SHx, .GLx). It's the file format used by the MSX BASIC
    for images smaller than the screen (also called shapes). An optional .PLx
    file containing a single or eight 16-color palettes is usually paired to
    customize the colors of the image.
  - QLD format (.GRA): This is a little known image format with 8 fixed colors
    that was used on some Japanese BBSs
  - Makichan v1 (.MKI): An early Japanese image format that was quickly
    succeeded by the v2. It's mostly PC-98 oriented, with some rudimentary
    support for other platforms
  - Makichan v2 (.MAG): It was by far the most popular Japanese image format,
    with support for multiple platforms including the MSX2/2+. Achieves
    excellent compression ratios on par with the GIF format, and was widely
    used on MSX disk magazines in the late 80s and 90s.
  - Yanagisawa's PIC: Another Japanese multi-platform image format, mostly used
    on the Sharp X68000 due to its support for high-color. It also achieves
    excellent compression ratios, but was rarely used for MSX images. It will
    just be called "PIC" for the rest of this document.
  - Dynamic Publisher. This was a desktop publishing app for the MSX2. It used
    three different file types:
    - Page files (.PCT)
    - Font files (.FNT)
    - Stamp files (.STP, synonym for .SHx)
  - Sega Bitmap (.SBM): Image format used to store VRAM dumps of the Sega
    consoles: SG-1000, Sega Master System and Game Gear
  - ZX-Spectrum image (.SCR): Image format widely used to store VRAM dumps of
    the UK ZX-Spectrum computer.
  - Text files are also supported (.TXT, .DOC, .DIZ, .HED, .HIS, .ENG), with
    either ASCII or Shift_JIS encoding
  - Full support for the NEOS MA-20 "Version Up Adapter"
  - Runs on any MSX2 or higher with 64KB or more of RAM and 64KB or more of
    VRAM (128KB of VRAM is required for SCREEN7/higher and the TextViewer)
  - Supports MSX-DOS1 and MSX-DOS2(/Nextor), with subdirectory support on the
    latter

2) COMMAND LINE OPTIONS

  /A  Auto load .RGB files. Valid for QLD/MKI/MAG. Loads a .RGB file containg
      a palette instead of a PLx file. It's required for QL9 files. It must
      have the same file name as the image, but with the RGB extension.

  /Bn Ring the BEEP n times after the image is loaded.
      n = 0~9: required parameter that specifies the number of times to beep
      
  /C  Display a PIC image with more than 16 colors in SCREEN12 instead of the
      default SCREEN8. Cannot be used on MSX2.
  /Cn n = 0~9: Specify the color saturation level when using /C.
      The default is n=9, that means full saturation.

  /D  Display a PIC image with more than 16 colors in SCREEN8 using dithering

  /En Limit the scroll of MAG images exceeding 424 lines, in n*100 line steps
      counted from the top

  /F  Display the file name at the bottom of the screen. For banner images
      (images taller than the screen), the file name will be displayed at the
      top.

  /Gn Specifies a timer for the gallery mode (aka slide show), to auto-advance
      the images when no key is pressed after a certain amount of time.
      n = 0~9: Amount of time to wait after displaying a file. The formula for
      the delay is 0,5s * 2^(n+1).

  /K  Displays up to 212 lines instead of the standard 200 lines limit on MKI
      files

  /L  Left-justify images larger than the screen

  /M  Center images larger than the screen

  /N  Do not clear the screen before loading QLD/MKI/MAG

  /O  Display PIC image with more than 16 colors in SCREEN8 without dithering

  /R  Right-justify images larger than the screen

  /Sn Force a specific screen mode for BLOAD image files. Use for nonstandard
      extensions like .DAT. n=2~8, A~C

  /T  Convert SCREEN12 images to SCREEN8 with dithering on MSX2+ or higher.
      This is done by default on the MSX2.

  /W  Scale non-MSX MAG/MKI/QLD images to fit in the screen, also fixing the
      aspect ratio
      
  /@  Infinite loop the gallery mode. Will start again after the last file
      is displayed. *Do not use* on empty folders/disks, as it will freeze
      the computer


3) KEYS ON THE IMAGE VIEWER MODE

  This mode displays a single or multiple images. A brief description of each
  key that can be pressed while viewing the image is listed here. Check the
  description of the respective letter on the COMMAND LINE OPTIONS above for
  more details.
  When wildcards are used, the ImageViewer starts in "gallery mode" (aka slide
  show), where the images are loaded in sequence and can be paged forward or
  backwards, with an optional timer to auto-advance the images when no key
  is pressed.

  [A] Turn ON/OFF the automatic loading switch of the [.RGB] file redisplay the
      image

  [C] Enable the display of PIC and SCREEN12 images on SCREEN12.

  [D] Enable the display PIC/MAG images with more than 16 colors and SCREEN12
      images in SCREEN8 with dithering.

  [F] Turn ON/OFF the file name display.

  [HOME] Enable the display images larger than the screen centered.

  [K] Turn ON/OFF the MKI 212 line switch.

  [O] Enable the display PIC/MAG images with more than 16 colors and SCREEN12
      images in SCREEN8 without dithering.

  [W] Enable the display non-MSX MAG/MKI/QLD images by scaling them to fit in
      the screen, also adjusting the aspect ratio. Ordered dithering
      (AKA checkerboard dithering) present on images might look broken though.

  [Z] Show 8-color PIC images in grayscale.

  [UP] Scrolls the viewport up on the image

  [DOWN] Scrolls the viewport down on the image

  [LEFT] Redisplay images larger than the screen left-justified.

  [RIGHT] Redisplay images larger than the screen right-justified.

  [0]~[9]
   - PIC images: Adjust the saturation level when displaying in SCREEN12
      (see /Cn)
   - Other image formats: Select between the available palettes. When a
     respective PLx file is found, it will select between the available
     palettes in that file.
   - SC2/SC3 and SRx files, when no respective PLx file is found, will have
     the following MSX1 palette approximations available. Also for SBM files
     containing SG-1000 images:
     1: TMS9x18
     2: TMS9x28
     3: V99x8
     4: CoolColors
     5: Sega Master System
     6: MSX1FRS (default when no embedded palette is found)
     7: Embedded palette in SC2/SC3 files

  [<] Select the previous different palette, or decrease the saturation level
      for PIC images displayed in SCREEN12

  [>] Select the next different palette, or increase the saturation level
      for PIC images displayed in SCREEN12

  [ESC]
     Stop viewing the image and return to DOS or File Manager.

  [ENTER]
     In Gallery mode, advance to the next image. Otherwise, return to the
     File Manager or DOS.

  [BS]
     In Gallery mode, go back to the previous file. Up to 255 last files can
     be viewed. Otherwise, return to the File Manager or DOS.


4) KEYS ON THE FILE MANAGER

  The following keys are available as commands for the File Manager:

  [DEL] Delete files. Can't delete folders.

  [D] Change the current drive, or refresh the file list
      (i.e., after changing the disk)

  [F2] Rename the selected file. Cannot rename folders.
      Can also use wildcards like * and ?

  [F3] Find wildcard pattern for the file list. The pattern follows the DOS
      standard, like *.MAG.

  [M] Move a file

  [S] Sort the file list. Will ask for F/E to sort by filename or extension,
      then U/D to sort "Up" or "Down" (ascending or descending order)

  [/] Set the command line option switches again. If there is a typo,
      it will terminate to DOS.

  [ENTER] Display an image or text file. On MSX-DOS2/Nextor, will also enter
      folders.

  [*] Starts a gallery (slide show) in this folder with the current file mask
      pattern

  [ESC] Exit and RETURN to DOS. Also cancels additional prompts made for some
      commands.


5) JOYSTICK OPERATION

Joystick support was added on BLS v3.x. The following commands are supported:

		  File Manager			Image Viewer
		---------------------------------------------------------------
  - UP		: up in file list		scrolls up on the image
  - DOWN	: down in file list		scrolls down on the image
  - LEFT	: left in the file list		show image left justified
  - RIGHT	: right in the file list	show image right justified
  - T1		: open a file/folder		ENTER (Next image)
  - T2		: -				BS (Previous image)
  - hold T1:	---------------------------------------------------------------
   - UP		: -				HOME (center justified)
   - DOWN	: -				W (downscale to fit)
   - LEFT	: -				< (Prev palette/PIC saturation)
   - RIGHT	: -				> (Next palette/PIC saturation)
  -  holt T2:	---------------------------------------------------------------
   - UP		: -				-
   - DOWN	: * (start a gallery here)	-
   - LEFT	: ESC				ESC
   - RIGHT	: F (Find Pattern)		F (Toggle name display)


6) ENVIRONMENT VARIABLES

On MSX-DOS2/Nextor, the BLS environment variable can be set to configure your
preferred defaults.

	Ex: SET BLS=/M/D ; Dither display with centering
	    SET BLS=/N/C/C4 ; No screen blanking / PIC shown in SCREEN12.


7) KNOWN ISSUES

- MSX2 machines with 64KB of VRAM will show garbage if any screen mode that
  requires 128KB of VRAM is used, or on the TextViewer
- MAG: 
  - The scroll is being set one line above than it should for some files.
  - Some horizontal banner images will only be shown left-justified.
  - Banner images taller than 256 lines can only be scrolled up to their last
    256 lines.
  - There's no horizontal scroll yet. The image will be redrawn cropped to the
    left, center or right.
- PCT: No support for scrolling yet. The whole image is already loaded to the
  VRAM though.
- SCx: Some images saved by MIFui have an incorrect size value on the BLOAD
  header. This will result in spurious sprites showing up for those images
  in gallery mode. It's not a bug on BLS.COM
- Depending on the palette, the filename text might be unreadable on SCR4 to
  SCR7.
- When the Z option, used to display PIC images in grayscale, is requested
  for 16-color images, only the first half of the colors will be displayed in
  grayscale.
- MSX2+ to MSX2 conversion:
  - The SCREEN10/11 are treated SCREEN12. This means that the colors will look
    off, but it's still better on an MSX2 than without any conversion.
  - Vertical banner images are not fully supported. Only parts of the image
    will be converted
- PIC: Native MSX images are accepting the dithering/force-SCR12 parameters
  (and respective keys D/C on the viewer), when they shouldn't, resulting in
  incorrect conversions

8) CHANGELOG

Only the BLS v3.x and higher changelog will be shown here. For older versions,
check their README file.

- v3.0A
  - Added Joystick support
  - Fixed Engrish texts
  - Reduced the minimal VRAM requirement to 64KB, as long as the SCREEN modes
    higher than 6 are not used.
  - File Manager:
    - Replaced ==== with ??? on the app title bar
    - Bugfix: When the drive was changed, trying to enter a folder caused a
      crash with "Directory not found" error
    - Bugfix: Hidden files wer shown on the File Manager: FLN complementary
      entries ended up appearing
    - Bugfix: Directories that had an extension crashed with "DIRECTORY NOT
      FOUND" error when trying to open them.
    - Replaced the <\> with [] to represent directories in the listing
    - Changed the following key commands
      - DEL = Delete
      - D = Select the drive/reload directory
      - F2 = Rename
  - Image Viewer:
    - Added support for SC2 to SC4 images
    - Added support for sprites on SCx files
    - Optimized the SCx VRAM load routine
    - SC12 to SC8 conversion now works for any image format, not only SCx/SRx
    - Set the border/background color before loading the image
    - Clear the keyboard buffer after loading an image
    - Turbofix: the wildcard gallery delay timer. New /Gn values = 0,5s*2^(n+1)
    - Removed the BSAVE image function (CTRL+G) to free space for the new
      routines
    - All keys now work normally in the auto gallery mode, including
      SPACE/BACKSPACE to go to the next/previous image
    - MAG loader:
      - Use SCREEN5 instead of SCREEN7 for SCREEN5 images
      - Bugfix: crash with SCREEN6 images
      - Bugfix doens't set the intelace mode accordingly for many files
      - Bugfix: C: Reloads the image centered, but resets incorrectly the
        scroll position
      - Added support to scroll up/down (up to 256 lines) after the image is
        loaded
    - Press D to enable "/T" conversion of SCR12 to SCR8, C to display it in
      SCR12.
    - Bugfix: Fix incorrect palette when displaying 16-color PIC images
    - Bugfix: Doesn't draw the filename when the images are taller than the
      screen. The name now is drown at the top for such images, as a workaround
      for the BIOS routines not being able to print at lines higher than 211
    - Bugfix: Unreadable filename text on SCR10 to 12
    - Optimization: Doesn't draws the filename on both pages only for
      interlaced images
    - Don't reload the image unnecessarily
      - When the file name display is enabled
      - When the SCREEN12 to SCREEN8 conversion is enabled
    - Changed the following key commands
      - SPACE: Next Image
      - Backspace: Previous Image
      - Left/Right: Change banner images justification
      - 0-9: Palette or PIC color difference on SCR12
      - Up/Down: Scroll up/down
    - Press 1 to 8 to select the palette
      - PLx files
      - Approximations of the MSX1 palette when needed
    - Press < and > to select the previous/next *different* palette (skips
      equal palettes in sequence)
    - Added support for:
      - Compressed Graph Saurus .SRx images
      - Interlaced Graph Saurus .SRI images
      - SHx/GLx
      - Dynamic Publisher PCT/FNT/STP images
      - ZX-Spectrum SCR images
      - Sega Bitmap (.SBM)
        - Sega Master System images
	- Game Gear images
	- SG-1000 images
  - Text Viewer:
    - Heavy optimization, resulting in much quicker startup and paging
    - Cached the MSX ROM fonts, so they're now only (re)loaded to the VRAM when
      they're not present, making consecutive starts of the text viewer even
      faster.
    - Only used for the TXT, DOC, DIZ, HED, HIS and ENG extensions. On BLS2
      it was used for any unknown file, which was annoying due to how slow
      it was to display a text file
    - Fixed the border color

9) FAQ

Q: I have some large MAG files that require a lot of scrolling. Why is this app
   so clumsy to show them?
A: The built-in MAG viewer is modest. BLS was mostly designed for image
   dimensions no larger than the screen. Some support for scrolling up/down is
   now present, but that's it. I also made sure that all MSX2/2+ screen modes,
   interlaced or not, would be properly supported without internal conversion
   (originally, BLS only supported the MAG format for SCREEN7 and higher, and
   converted images from other screen modes to those).
   Tip: If you need to see MAG files of any dimension, with full support for
   scrolling, you'll be better served by DMAG.COM

Q: Would you support <this or that> file format?
A: I wanted to provide a single tool that any user could easily/quickly enjoy,
   on their own *real* MSX, the majority of the images present on the MSX Pixel
   Art Collections I publish.
   I felt frustrated that it was so cumbersome to try to see Pixel Art on the
   real MSX. I had to resort to a lot of clumsy command-line-only tools, and
   except for DMAG.COM, there was no joystick support to see a collection
   comfortably from the sofa.
   Also, I wanted to have a way to leave an unattended MSX showing a selection
   of images in automatic slideshow on an MSX (or any retro) meeting.
   As a bonus, I wanted to support SBM and SCR so MSX users could enjoy the
   SMS/GG and ZX-Spectrum images in their native formats, without any need for
   conversion.
   Sadly, I've run out of free time and MIF/MIG support had to be postponed.

Q: Why did you change this or that <specific characteristic>? This is an
   unacceptable heresy, and shouldn't have been done!!!
A: I changed what I needed for my personal use and for some close friends, and
   am also sharing for those who might enjoy what took hundreds of hours of my
   effort to cook. Nobody has any obligation to use if they don't like it.

Q: Could you do a custom version just for me, tuned to the way I want?
A: No. Whatever I choose to share is for the benefit of most MSX users as
   possible.
   When a single person want to benefit alone from the works of others, it is
   not a hobby anymore and should not be expected to made for free.

Q: Why so many different "MSX1" palettes? That's confusing! Which one is
   the correct?
A: The MSX2 can't perfectly reproduce the MSX1 palette, period. That said,
   it's because of some reasons, mainly:
   1) The TMS99x8 VDP has a 12bit DAC, while the V9938 has a 9bit DAC
   2) On top of that, the TMS99x8 outputs a different color system (YUV) and
      the conversion to RGB is done by analog circuitry. IOW, you would need
      some more bits to try to represent that in the digital domain.
   3) On top of (2), unlike RGB, YUV is a color system that gives a lot of
      freedom for the engineers to tweak, and... tweaking they did. A lot.
      The most usual tweaking seems to have been a flat reduction the
      saturation to 50%. I suspect that this was probably a cheap workaround
      for some TMS colors coming out too hot, resulting out of scale RGB colors
      that otherwise would require a more expensive saturation circuit, and as
      a bonus it resulted in a more pastel palette that certainty pleased the
      Japanese engineers eyes.
   With all that out of the way, there's no single palette what will perfectly
   capture all the nuances of what was originally drawn. Concessions have to be
   made, resulting that, per image, some will look better than others.
   Because of this, I gave you then 4 "native" variations of the MSX1 palette
   to try which one looks better to you for which image, plus 3 others with
   more daring colors as a bonus. The first three and the SMS one also have
   numbers associated with their VDP codes, as a mnemonic:
   1) TMS9918 (approximation)
   2) TMS9928 with 50% saturation (approximation)
   3) V9938
   4) CoolColors (My bold palette, intended to improve the look of some games)
   5) Sega Master System (So you can easily check how games and images will
      look on that VDP)
   6) ZX-Spectrum (The best to use with ZX-Spectrum conversions)
   7) FRS1MSX (My conservative palette, finely tweaked to look as close as
      possible to the MSX1 that the V9938 can reproduce while still keeping
      gradients coherent)

Q: But I really miss the CTRL+G function to save files in BSAVE format. Will
   it ever come back?
A: That was a very useful function at a time that no emulators existed and
   most people only had MSX software to edit images. But that feature used
   quite some precious memory space and would need even more to be fixed and
   to support the other screen modes I added. I personally think that more
   polishing and support for other file formats was a more noble use of that
   memory space.
   Tip: If you just want to BSAVE the image that's on the MSX screen, the
   openMSX emulator has a very useful script: save_msx_screen


10) THANKS AND CREDITS

- SEIGA, for the original BLS v2.00. It was such a great image viewer for its
  time. Please let me know if you like this enhanced patched version. Also,
  if you still have its source code, I would love to have access to it.
- The openMSX team, for their excellent emulator and debugger
- The sjasmplus team, for this assembler with such a great built-in support
  for patch creation
- Pedro de Medeiros, AKA pvmm, for the many improvements he have been making
  on the openMSX debugger. My productivity have become much higher because of
  this.
- Louthrax, for his converter MIFui. (note: sorry, MIF/MIG support was
  planned but had to be postponed since my free time got scarse again)
- Sandro Sebastiao Singer, for testing and manual revision


11) COPYRIGHTS

 MSX/MSX2/MSX2+ (TM) MSX Licensing Corporation
 BLS2.00        Copyright SEIGA  , 1993
 QLD     Loader Copyright MAJYO  , 1988
 PIC     Loader Copyright AKIRA_Y, 1989
 MAKI    Loader Copyright W_RINN , 1989
 MAG     Loader Copyright W_RINN , 1991
 MAX     Loader Copyright MERON  , 1991
 SHx     Loader Copyright FRS    , 2023
 SBM     Loader Copyright FRS    , 2023
 SCR     Loader Copyright FRS    , 2023
 Compressed Graph Saurus Loader Copyright FRS, 2023
 Interlaced Graph Saurus Loader Copyright FRS, 2023
 Dynamid Publisher PCT   Loader Copyright FRS, 2023
 Dynamid Publisher FNT   Loader Copyright FRS, 2023
 Dynamid Publisher STP   Loader Copyright FRS, 2023
 CoolColors palette		Copyright FRS, 1997
 MSX1FRS    palette		Copyright FRS, 2021


===========================================================================
	                     License
                           Terms of use
---------------------------------------------------------------------------

1) This software is gratis for non-commercial purposes, and the original author
   retains its copyright. You only can run, make backup copies or distribute
   this software while observing the non-commercial restriction.

2) You are only allowed distribute this software (online or on a removable
   media) under the following conditions:
   2.1) No commercial transaction of any kind is involved.
   2.2) All the original files are distributed together inside the same
   compressed file.
   2.3) This README must be included unmodified inside the same compressed file.

3) If you want to use this software for commercial purposes you MUST contact
   the original author (SEIGA) to negotiate the terms and conditions.

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

5) USE THIS SOFTWARE SOLELY AT YOUR OWN RISK.

