Merge branch '86Box:master' into master

icons.sh

@@ -0,0 +1,42 @@
+#!/bin/sh
+
+# Check for repository path.
+if [ -z "$1" ]
+then
+	echo Specify 86Box repository path. ImageMagick is required.
+	exit 1
+fi
+
+# Determine the ImageMagick executable.
+magick=magick
+$magick >/dev/null 2>&1 || magick=magick.exe
+
+# Convert icons to PNG.
+for i in "$1/src/win/icons/"*.ico
+do
+	$magick convert "$i" "usage/images/$(basename $i | sed -e 's/.ico$//').png"
+done
+
+# Remove unnecessary icons.
+cd usage/images
+rm -f 86Box-* *_empty* *_active* *_disabled* *-1.png *-2.png
+
+# Get small and big icons.
+for i in *-0.png
+do
+	mv "$i" "$(echo $i | sed -e 's/-0/_small/')"
+done
+for i in *-3.png
+do
+	mv "$i" "$(echo $i | sed -e 's/-3//')"
+done
+for i in *-4.png
+do
+	mv "$i" "$(echo $i | sed -e 's/-4//')"
+done
+
+# Create include.rst entries.
+for i in *.png
+do
+	echo '.. |'$(echo $i | sed -e 's/.png//')'| image:: /usage/images/'$i
+done

include.rst

@@ -4,6 +4,8 @@
 .. |vel| unicode:: 0x22EE
    :trim:
 
+.. |acpi_shutdown| image:: /usage/images/acpi_shutdown.png
+.. |acpi_shutdown_small| image:: /usage/images/acpi_shutdown_small.png
 .. |cartridge| image:: /usage/images/cartridge.png
 .. |cartridge_small| image:: /usage/images/cartridge_small.png
 .. |cassette| image:: /usage/images/cassette.png
@@ -20,6 +22,8 @@
 .. |floppy_and_cdrom_drives_small| image:: /usage/images/floppy_and_cdrom_drives_small.png
 .. |hard_disk| image:: /usage/images/hard_disk.png
 .. |hard_disk_small| image:: /usage/images/hard_disk_small.png
+.. |hard_reset| image:: /usage/images/hard_reset.png
+.. |hard_reset_small| image:: /usage/images/hard_reset_small.png
 .. |input_devices| image:: /usage/images/input_devices.png
 .. |input_devices_small| image:: /usage/images/input_devices_small.png
 .. |machine| image:: /usage/images/machine.png
@@ -32,8 +36,18 @@
 .. |other_peripherals_small| image:: /usage/images/other_peripherals_small.png
 .. |other_removable_devices| image:: /usage/images/other_removable_devices.png
 .. |other_removable_devices_small| image:: /usage/images/other_removable_devices_small.png
+.. |pause| image:: /usage/images/pause.png
+.. |pause_small| image:: /usage/images/pause_small.png
 .. |ports| image:: /usage/images/ports.png
 .. |ports_small| image:: /usage/images/ports_small.png
+.. |run| image:: /usage/images/run.png
+.. |run_small| image:: /usage/images/run_small.png
+.. |send_cad| image:: /usage/images/send_cad.png
+.. |send_cad_small| image:: /usage/images/send_cad_small.png
+.. |send_cae| image:: /usage/images/send_cae.png
+.. |send_cae_small| image:: /usage/images/send_cae_small.png
+.. |settings| image:: /usage/images/settings.png
+.. |settings_small| image:: /usage/images/settings_small.png
 .. |sound| image:: /usage/images/sound.png
 .. |sound_small| image:: /usage/images/sound_small.png
 .. |storage_controllers| image:: /usage/images/storage_controllers.png

index.rst

@@ -26,6 +26,7 @@ Contents
    
    usage/gettingstarted
    usage/menubar
+   usage/toolbar
    usage/statusbar
    settings/index
 

settings/network.rst

@@ -30,4 +30,4 @@ Network card to emulate. Only cards supported by the machine's expansion buses w
 
 The *Configure* button opens a new window with settings specific to the selected network card, such as the I/O port and IRQ for ISA cards.
 
-The **[LPT] Parallel Port Internet Protocol** network adapter requires a **PLIP Network** device to be attached to a :ref:`parallel port <settings/ports:Parallel port 1-3>`.
+The **[LPT] Parallel Port Internet Protocol** network adapter requires a **PLIP Network** device to be attached to a :ref:`parallel port <settings/ports:Parallel port 1-4>`.

settings/ports.rst

@@ -5,7 +5,7 @@
 
 The *Ports (COM & LPT)* page contains settings related to the emulated machine's I/O ports.
 
-LPT1-3 Device
+LPT1-4 Device
 -------------
 
 Emulated device to connect to the given parallel (LPT) port.
@@ -42,7 +42,9 @@ Serial port 1-4
 
 Enable emulation of serial ports ranging from COM1 to COM4. Any ports not provided by the machine's motherboard will be emulated as generic ISA or VLB serial cards.
 
-Parallel port 1-3
+Parallel port 1-4
 -----------------
 
 Enable emulation of parallel ports ranging from LPT1 to LPT3. Any ports not provided by the machine's motherboard will be emulated as generic ISA or VLB parallel cards.
+
+.. note:: The 4th parallel port is not widely supported. It is located at I/O port 268h.

settings/removable.rst

@@ -12,7 +12,7 @@ Up to four Magneto-Optical and four Iomega ZIP disk drives can be attached to th
 
 * **Bus:** storage bus to attach the drive to. ATAPI (IDE) and SCSI are supported.
 * **Channel**/**ID:** where to attach the drive on the selected storage bus. See :ref:`settings/hdd:Adding a new disk` for more information.
-* **Type** (MO only): drive model to identify as. A list of drive models to choose from is provided.
+* **Type** (MO only): drive model to identify as. A list of drive models to choose from is provided. Each model supports different types of MO media, while the `86BOX` model supports all types.
 * **ZIP 250** (ZIP only): enable the drive to read and write 250 MB ZIP disks.
 
 MO / ZIP disk images can be inserted and removed through the :ref:`status bar <usage/statusbar:|zip| |mo| ZIP and MO drives>` or :ref:`Media menu <usage/menubar:Media>`.

settings/sound.rst

@@ -5,7 +5,7 @@
 
 The *Sound* page contains settings related to the emulated machine's audio hardware.
 
-Parallel port sound devices such as the **Disney Sound Source** and **Covox Speech Thing** are not present on this page; they can be configured through the :ref:`Ports page <settings/ports:LPT1-3 Device>`.
+Parallel port sound devices such as the **Disney Sound Source** and **Covox Speech Thing** are not present on this page; they can be configured through the :ref:`Ports page <settings/ports:LPT1-4 Device>`.
 
 Sound card
 ----------

settings/storage.rst

@@ -39,3 +39,5 @@ Cassette
 --------
 
 Enable IBM cassette tape emulation. The cassette deck can be controlled through the :ref:`status bar <usage/statusbar:|cassette| Cassette deck>` or :ref:`Media menu <usage/menubar:Media>`.
+
+.. note:: While cassette emulation can be enabled on any machine, it is only usable on the IBM PC, PCjr and other machines with an IBM cassette port.

usage/menubar.rst

@@ -11,31 +11,36 @@ Action
 * **Hard Reset:** force a reset of the emulated machine. Requires confirmation, which can be disabled by checking the *Don't show this message again* box.
 * **Ctrl+Alt+Del:** send a *Ctrl+Alt+Del* key combination to the emulated machine. You can alternatively press *Ctrl+F12* to send that combination.
 * **Ctrl+Alt+Esc:** send a *Ctrl+Alt+Esc* key combination to the emulated machine.
-* **Pause:** pause emulation. Uncheck this option to resume emulation.
-
-.. note:: Emulation is automatically paused when the emulated machine enters ACPI sleep mode.
-
+* **Pause:** pause emulation of the machine. Uncheck this option to resume emulation.
 * **Exit:** quit 86Box. Requires confirmation, which can be disabled by checking the *Don't show this message again* box.
 
 View
 ----
 
+* **Hide status bar:** hides the :doc:`status bar <statusbar>` at the bottom of the window.
+* **Hide toolbar:** hides the :doc:`toolbar <toolbar>` below the menu bar.
 * **Resizeable window:** allow the 86Box window to be freely resized. Unchecking this option will also return the window to its normal size.
 * **Remember size & position:** automatically save the size and position of the 86Box window to the emulated machine's configuration file.
-* **Renderer:** select a graphical renderer for the emulated display. *SDL (Hardware)* is recommended in most cases. *OpenGL (3.3 Core)* allows for shader effects to be applied to the emulated display, however, it is not compatible with older integrated GPUs.
-* **OpenGL options:** configure the *OpenGL (3.3 Core)* renderer. This submenu will be available if that renderer is selected.
+* **Renderer:** select a graphical renderer for the emulated display.
+
+   * **SDL (Hardware)** is recommended in most cases.
+   * **SDL (Software)** and **SDL (OpenGL)** are known to perform better on some host systems. Try these if your system is struggling to maintain 100% emulation speed.
+   * **OpenGL (3.0 Core)** allows for shader effects to be applied to the emulated display, however, it is not compatible with older integrated GPUs.
+
+* **OpenGL options:** configure the *OpenGL (3.0 Core)* renderer. This submenu will be available if that renderer is selected.
 
    * **Target framerate:** select the framerate at which the emulated display is updated. *Sync with video* uses the emulated display's current refresh rate.
    * **VSync:** enable vertical sync. Recommended if tearing artifacts are observed.
    * **Select shader:** load a .glsl shader file to apply on the emulated display. Many shaders are available for simulating CRT displays, VHS tapes and other aesthetics; the `RetroArch glsl-shaders repository <https://github.com/libretro/glsl-shaders>`_ is a good place to start.
    * **Remove shader:** disable the currently-loaded shader.
 
-.. note:: Shaders that take advantage of multipass and previous frames are not supported.
+.. note:: * Shaders that take advantage of multipass and previous frames are not supported.
+          * ``.cg`` and ``.cgp`` shaders are not supported either, as these formats are long deprecated.
 
 * **Specify dimensions:** open a window where an exact size (in pixels) for the emulated display can be set. If checked, the *Lock to this size* box prevents changes in the emulated display's resolution from overriding the specified size.
 * **Force 4:3 display ratio:** stretch the emulated display to a 4:3 aspect ratio, independently of the emulated machine's screen resolution.
-* **Window scale factor:** scale the emulated display to half (0.5x), normal (1x), 50% larger (1.5x) or double (2x) sizes.
-* **Filter method:** select the filtering method (Nearest or Linear) to be used when scaling the emulated display.
+* **Window scale factor:** scale the emulated display to half (*0.5x*), normal (*1x*), 50% larger (*1.5x*) or double (*2x*) sizes.
+* **Filter method:** select the filtering method (*Nearest* or *Linear*) to be used when scaling the emulated display.
 * **HiDPI scaling:** automatically scale the emulated display to real size if your host system has a HiDPI display. This option can be used alongside *Window scale factor* above.
 * **Fullscreen:** enter full screen mode. Press *Ctrl+Alt+Page Down* to go back to windowed mode. You can also enter full screen mode by pressing *Ctrl+Alt+Page Up*.
 * **Fullscreen stretch mode:** select the picture mode to use when in full screen mode.
@@ -48,8 +53,8 @@ View
 * **EGA/(S)VGA settings:** contains display settings specific to EGA, VGA and Super VGA video hardware.
 
    * **Inverted VGA monitor:** emulate a VGA monitor with inverted colors.
-   * **VGA screen type:** select the VGA monitor type to emulate. Color, grayscale, amber phosphor, green phosphor and white phosphor monitors can be selected.
-   * **Grayscale conversion type:** select the color-to-grayscale conversion profile (BT.601, BT.709 or Average) to use when a grayscale monitor is selected.
+   * **VGA screen type:** select the VGA monitor type to emulate. *Color*, *Grayscale*, *Amber*, *Green* and *White* phosphor monitors can be selected.
+   * **Grayscale conversion type:** select the color-to-grayscale conversion profile (*BT.601*, *BT.709* or *Average*) to use when a grayscale monitor is selected.
 
 * **CGA/PCjr/Tandy/EGA/(S)VGA overscan:** add an overscan border around the display. This border is only added when emulating the specified video hardware types.
 * **Change contrast for monochrome display:** optimize the contrast of monochrome CGA monitors for 4-color operation.
@@ -62,7 +67,7 @@ This menu lists all storage drives attached to the emulated machine, and provide
 Tools
 -----
 
-* **Settings:** open the :doc:`Settings <../settings/index>` window.
+* **Settings:** open the :doc:`Settings <../settings/index>` window to configure the emulated machine.
 * **Update status bar icons:** enable the activity lights on :doc:`status bar <statusbar>` icons. Unchecking this option may improve emulation performance on low-end host systems.
 * **Preferences:** open the *Preferences* window, which provides the following options:
 

usage/toolbar.rst

@@ -0,0 +1,42 @@
+.. include:: /include.rst
+
+Toolbar
+=======
+
+The toolbar located at the top of the 86Box window (right below the :doc:`menu bar <menubar>`) has two purposes: it provides quick actions for the emulated machine on its left hand side, and displays status information on its right hand side.
+
+|pause| |run| Pause/resume execution
+------------------------------------
+
+Pause emulation of the machine. Press again to resume emulation.
+
+.. note:: Emulation is automatically paused when the emulated machine enters ACPI sleep mode.
+
+|hard_reset| Hard reset
+-----------------------
+
+Force a reset of the emulated machine. Requires confirmation, which can be disabled by checking the *Don't show this message again* box.
+
+|acpi_shutdown| ACPI shutdown
+-----------------------------
+
+Initiate a clean shutdown of the emulated machine. Only available on machines with ACPI soft power off capability.
+
+|send_cad| |send_cae| Press Ctrl+Alt+Del/Ctrl+Alt+Esc
+-------------------------------------------------------
+
+Send a *Ctrl+Alt+Del* (left-most icon) or *Ctrl+Alt+Esc* (right-most icon) key combination to the emulated machine. You can alternatively press *Ctrl+F12* to send a *Ctrl+Alt+Del* combination.
+
+|settings| Settings
+-------------------
+
+Open the :doc:`Settings <../settings/index>` window to configure the emulated machine.
+
+Status area
+-----------
+
+The right hand side of the toolbar displays status information, such as:
+
+* **Emulation speed** in percentage. If this number stays consistently below 100%, your host system is not keeping up with emulating the configured hardware.
+* **Mouse state** (captured or released) if a :ref:`mouse <settings/input:Mouse>` is enabled.
+* **Pause indicator** if emulation is paused.