diff --git a/icons.sh b/icons.sh new file mode 100644 index 0000000..2c57dc3 --- /dev/null +++ b/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 diff --git a/include.rst b/include.rst index 917558f..372044b 100644 --- a/include.rst +++ b/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 diff --git a/index.rst b/index.rst index 894bacc..60b39e0 100644 --- a/index.rst +++ b/index.rst @@ -26,6 +26,7 @@ Contents usage/gettingstarted usage/menubar + usage/toolbar usage/statusbar settings/index diff --git a/settings/network.rst b/settings/network.rst index 785f064..6d65b65 100644 --- a/settings/network.rst +++ b/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 `. +The **[LPT] Parallel Port Internet Protocol** network adapter requires a **PLIP Network** device to be attached to a :ref:`parallel port `. diff --git a/settings/ports.rst b/settings/ports.rst index 94733a3..980bc72 100644 --- a/settings/ports.rst +++ b/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. diff --git a/settings/removable.rst b/settings/removable.rst index 68384a4..e58f025 100644 --- a/settings/removable.rst +++ b/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 ` or :ref:`Media menu `. diff --git a/settings/sound.rst b/settings/sound.rst index b8cee23..1721754 100644 --- a/settings/sound.rst +++ b/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 `. +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 `. Sound card ---------- diff --git a/settings/storage.rst b/settings/storage.rst index c531ce4..d28250b 100644 --- a/settings/storage.rst +++ b/settings/storage.rst @@ -39,3 +39,5 @@ Cassette -------- Enable IBM cassette tape emulation. The cassette deck can be controlled through the :ref:`status bar ` or :ref:`Media menu `. + +.. 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. diff --git a/usage/images/acpi_shutdown.png b/usage/images/acpi_shutdown.png new file mode 100644 index 0000000..1add56b Binary files /dev/null and b/usage/images/acpi_shutdown.png differ diff --git a/usage/images/acpi_shutdown_small.png b/usage/images/acpi_shutdown_small.png new file mode 100644 index 0000000..589e6dc Binary files /dev/null and b/usage/images/acpi_shutdown_small.png differ diff --git a/usage/images/cartridge.png b/usage/images/cartridge.png index 8cc8d5d..4edb02e 100644 Binary files a/usage/images/cartridge.png and b/usage/images/cartridge.png differ diff --git a/usage/images/cassette.png b/usage/images/cassette.png index bd4b06f..3a327dd 100644 Binary files a/usage/images/cassette.png and b/usage/images/cassette.png differ diff --git a/usage/images/cdrom.png b/usage/images/cdrom.png index 6db2243..a14cb17 100644 Binary files a/usage/images/cdrom.png and b/usage/images/cdrom.png differ diff --git a/usage/images/display.png b/usage/images/display.png index 9f2da1a..dcda9e8 100644 Binary files a/usage/images/display.png and b/usage/images/display.png differ diff --git a/usage/images/floppy_35.png b/usage/images/floppy_35.png index 1224473..afd2295 100644 Binary files a/usage/images/floppy_35.png and b/usage/images/floppy_35.png differ diff --git a/usage/images/floppy_525.png b/usage/images/floppy_525.png index 9573b5c..e509d4a 100644 Binary files a/usage/images/floppy_525.png and b/usage/images/floppy_525.png differ diff --git a/usage/images/hard_disk.png b/usage/images/hard_disk.png index bfec73d..8167e2c 100644 Binary files a/usage/images/hard_disk.png and b/usage/images/hard_disk.png differ diff --git a/usage/images/hard_reset.png b/usage/images/hard_reset.png new file mode 100644 index 0000000..f747259 Binary files /dev/null and b/usage/images/hard_reset.png differ diff --git a/usage/images/hard_reset_small.png b/usage/images/hard_reset_small.png new file mode 100644 index 0000000..9376cf0 Binary files /dev/null and b/usage/images/hard_reset_small.png differ diff --git a/usage/images/input_devices.png b/usage/images/input_devices.png index 446fea5..1027c60 100644 Binary files a/usage/images/input_devices.png and b/usage/images/input_devices.png differ diff --git a/usage/images/machine.png b/usage/images/machine.png index 7271219..54b23ef 100644 Binary files a/usage/images/machine.png and b/usage/images/machine.png differ diff --git a/usage/images/mo.png b/usage/images/mo.png index cd58e61..bb0e262 100644 Binary files a/usage/images/mo.png and b/usage/images/mo.png differ diff --git a/usage/images/network.png b/usage/images/network.png index b0f638c..6b64383 100644 Binary files a/usage/images/network.png and b/usage/images/network.png differ diff --git a/usage/images/other_peripherals.png b/usage/images/other_peripherals.png index 3f4a4f4..5d56c6f 100644 Binary files a/usage/images/other_peripherals.png and b/usage/images/other_peripherals.png differ diff --git a/usage/images/other_removable_devices.png b/usage/images/other_removable_devices.png index 96d5566..68e0ba2 100644 Binary files a/usage/images/other_removable_devices.png and b/usage/images/other_removable_devices.png differ diff --git a/usage/images/pause.png b/usage/images/pause.png new file mode 100644 index 0000000..82bf0ec Binary files /dev/null and b/usage/images/pause.png differ diff --git a/usage/images/pause_small.png b/usage/images/pause_small.png new file mode 100644 index 0000000..e4cd2df Binary files /dev/null and b/usage/images/pause_small.png differ diff --git a/usage/images/ports.png b/usage/images/ports.png index 118954c..15d6ba7 100644 Binary files a/usage/images/ports.png and b/usage/images/ports.png differ diff --git a/usage/images/run.png b/usage/images/run.png new file mode 100644 index 0000000..05244e7 Binary files /dev/null and b/usage/images/run.png differ diff --git a/usage/images/run_small.png b/usage/images/run_small.png new file mode 100644 index 0000000..fc37d25 Binary files /dev/null and b/usage/images/run_small.png differ diff --git a/usage/images/send_cad.png b/usage/images/send_cad.png new file mode 100644 index 0000000..be98e80 Binary files /dev/null and b/usage/images/send_cad.png differ diff --git a/usage/images/send_cad_small.png b/usage/images/send_cad_small.png new file mode 100644 index 0000000..8bbce1e Binary files /dev/null and b/usage/images/send_cad_small.png differ diff --git a/usage/images/send_cae.png b/usage/images/send_cae.png new file mode 100644 index 0000000..d95c41d Binary files /dev/null and b/usage/images/send_cae.png differ diff --git a/usage/images/send_cae_small.png b/usage/images/send_cae_small.png new file mode 100644 index 0000000..9879e3c Binary files /dev/null and b/usage/images/send_cae_small.png differ diff --git a/usage/images/settings.png b/usage/images/settings.png new file mode 100644 index 0000000..eb129fd Binary files /dev/null and b/usage/images/settings.png differ diff --git a/usage/images/settings_small.png b/usage/images/settings_small.png new file mode 100644 index 0000000..bb5eb1f Binary files /dev/null and b/usage/images/settings_small.png differ diff --git a/usage/images/sound.png b/usage/images/sound.png index 5a12149..cdf8be2 100644 Binary files a/usage/images/sound.png and b/usage/images/sound.png differ diff --git a/usage/images/storage_controllers.png b/usage/images/storage_controllers.png index ba965c0..740831e 100644 Binary files a/usage/images/storage_controllers.png and b/usage/images/storage_controllers.png differ diff --git a/usage/images/zip.png b/usage/images/zip.png index 916eb43..baa7720 100644 Binary files a/usage/images/zip.png and b/usage/images/zip.png differ diff --git a/usage/menubar.rst b/usage/menubar.rst index c12e95b..f5bf585 100644 --- a/usage/menubar.rst +++ b/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 ` at the bottom of the window. +* **Hide toolbar:** hides the :doc:`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 `_ 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 ` icons. Unchecking this option may improve emulation performance on low-end host systems. * **Preferences:** open the *Preferences* window, which provides the following options: diff --git a/usage/toolbar.rst b/usage/toolbar.rst new file mode 100644 index 0000000..2f74996 --- /dev/null +++ b/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 `) 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 ` is enabled. +* **Pause indicator** if emulation is paused.