Setting up printing in DOSBox-X

Overview

DOSBox-X has support for printing to either a real printer, redirect to a file, or create a PNG, BMP or PostScript file.

Printer options in the DOSBox-X config file are split over two sections, [parallel] and [printer].

The Virtual Printer option emulates a colour dot-matrix printer that follows the Epson ESC/P2 printing standard.

Example of printers that may work:

These are examples of printers that you may be able to select in a DOS application, which may work with the virtual printer option.

  • Epson MX-80

  • Epson SQ-860

  • Epson LQ-800

  • IBM Pro Printer

  • Generic ESC/P 24pin wide (Windows 3.11 running in DOSBox-X)

  • Generic / Text Only (Windows running in DOSBox-X)

Features:

  • Many of the Epson ESC/P and ESC/P2 instructions are supported

  • Graphics printing for 24-pin and 48-pin modes supported, up to 360dpi

  • Colour output, use "Generic ESC/P 24pin wide" printer on Windows 3.11 or "Epson SQ 860" on Win95

  • Data can be output as Windows bitmap, PNG file, PostScript file, or sent to a Windows

  • Some older non-conflicting IBM control codes are supported

Limitations:

  • Windows printer output in black & white only

  • Not all ESC/P commands are supported, like custom fonts

  • Due to over-exact graphics emulation 360dpi printing from Windows (guest) graphics rastering might not look as expected

  • When set to use a Windows printer, the printer dialogue will only show up once at start

  • Country code setup and other configuration switches and buttons found on a real printer are not available, this may be overcome by sending special ESC/P commands to the printer before printing

[parallel] section options

This section lists the available configuration options for the [parallel] section that DOSBox-X provides.

parallel1

  • Default value: disabled

  • Possible values: disabled, reallpt, file, printer, disney

This enables an emulated LPT1 port on IO base address 0x378. Most DOS applications expect a printer on LPT1 port.

Some values have additional parameters, which if specified must be on the same line in the form of parameter:value.

disabled

  • Disables the printer port emulation

Note: the parallel1 port may be auto-enabled for Disney Sound Source emulation.

reallpt

  • Windows:

    • realbase (the base address of your real parallel port).

      • Default: 378

    • ecpbase (base address of the ECP registers, optional).

  • Linux:

    • realport (the parallel port device i.e. /dev/parport0).

file

  • dev:<devname> (i.e. dev:lpt1) to forward data to a device

  • append:<file> appends data to the specified file.

Without one of the above parameters, data is written to files in the capture directory.

  • Additional parameters:

    • timeout:<milliseconds> = how long to wait before closing the file on inactivity (default:500)

    • squote squote to use single quotes instad of double quotes for quoted program commands

    • addFF to add a formfeed when closing

    • addLF to add a linefeed if the app doesn’t

    • cp:<codepage number> to perform codepage translation, i.e. cp:437

    • openps:<program> start a program to open the file if the printer output is detected to be PostScript.

    • openpcl:<program> start a program to open the file if the printer output is detected to be PCL.

    • openwith:<program> start a program to open the file in all other conditions.

    • openerror:<program> start a program to open the file if an error had occurred.

Example:

[parallel]
parallel1=file dev:lpt1 timeout=1000 addFF cp:437

printer

Printer has it’s own configuration section below.

disney

Defines that this port has the emulated Disney Sound Source attached (Covox Voice Master and Covox Speech Thing compatible). It requires the following lines in your config:

[speaker]
disney=true

[parallel]
parallel1=disney

If you want to have Disney Sound Source emulation, you need to set disney=true in the [speaker] section. In addition the parallel1= value needs to be either set to disabled (will be auto-enabled for the Disney Sound Source emulation), or disney. Alternatively you can move the Disney Sound Source on a different parallel port, but most games expect it on the first by default.

If you set disney=true and have parallel1= set to a different value, the Disney Sound Source emulation will not work.

parallel2

  • Default value: disabled

  • Possible values: disabled, reallpt, file, printer, disney

This enables an emulated LPT2 port on IO base address 0x278.

parallel3

  • Default value: disabled

  • Possible values: disabled, reallpt, file, printer, disney

This enables an emulated LPT3 port.

parallel4-9

  • Default value: disabled

  • Possible values: disabled, reallpt, file, printer, disney

Note
LPT1-3 are standard LPT ports in DOS, whereas LPT4-9 are extended LPT ports that are only supported by some applications. You can optionally specify base addresses and IRQs for them with base: and irq: options.

dongle

  • Default value: false

  • Possible values: false, true

When set to true, emulates an Atmel 93c46 based dongle attached to the LPT1 port. Examples of such dongles are the Rainbow Sentinel Cplus and MicroPhar.

Unfortunately this feature is rather incomplete at this time, and requires that dongle.cpp in the source code is edited and the right bytes for the dongle to be emulated are entered in the MEMORY array. After which DOSBox-X needs to be re-compiled.

[printer] section options

This section lists the available configuration options for the [printer] section that DOSBox-X provides.

Only one printer can be emulated, and it can only be connected to a single virtual parallel port. It is also necessary for the virtual printer to configure TrueType fonts.

printer

  • Default value: false

  • Possible values: true, false

Enables or disables printer emulation.

dpi

  • Default value: 360

  • Possible values:

width

  • Default value: 85

  • Possible values:

Width of paper in 1/10 inch. The default 85 corresponds to 8.5".

Example of standard paper sizes in portrait orientation:

  • Letter = 85 (default)

  • Legal = 85

  • A3 = 116 (297mm = 11.69 inches)

  • A4 = 82 (210mm = 8.27 inches)

  • A5 = 58 (148mm = 5.83 inches)

height

  • Default value: 110

  • Possible values:

Height of paper in 1/10 inch. The default 110 corresponds to 11.0".

Example of standard paper sizes in portrait orientation:

  • Letter = 110 (default)

  • Legal = 140

  • A3 = 165 (420mm = 16.53 inches)

  • A4 = 116 (297mm = 11.69 inches)

  • A5 = 82 (210mm = 8.27 inches)

printoutput

  • Default value: png

  • Possible values: png, ps, bmp, printer

Between PNG and BMP, PNG is better. BMP files will be much larger, while the image quality will be identical.

ps = PostScript.

Setting the value to printer on a Windows host, will cause it to get redirected to your print queue and a print dialogue will appear.

multipage

  • Default value: false

  • Possible values: true, false

Only applicable if printoutput=ps.

Adds all pages to one PostScript file or printer job until CTRL-F2 is pressed. See also the timeout option below.

docpath

  • Default value: .

The path where the output files are stored. Defaults to the current working directory.

Note: On Linux the use of the ~ character is not allowed to specify the home directory.

openwith

  • Default value: \<blank\>

Start the specified program to open the output file.

e.g. openwith=notepad will open the file with Notepad on a Windows host.

Some examples: - Linux host: openwith=xdg-open will cause the file to be opened with the application associated with the file extension - Windows host: openwith=start will cause the file to be opened with the application associated with the file extension - Windows host: openwith=notepad will open the file with the Notepad application - macOS host: openwith=open -s "Preview" will cause the file to be opened with the application associated with the file extension

openerror

  • Default value: \<blank\>

Start the specified program to open the output file if an error had occurred.

timeout

  • Default value: 0

  • Possible values:

Timeout (in milliseconds).

If zero, the page will not be ejected until a form-feed is received.

Since not all software will send one, especially if your redirecting output, you can force a form-feed (eject page) by specifying a non-zero value.

If non-zero, it specifies the time after which the page will be ejected automatically when no more data arrives at the printer.

You can also manually eject a form-feed when you want to do so, and this option is available from the DOS menu.

Setting up fonts for the emulated printer

The emulated printer requires TrueType fonts in order to be able to print text. At a minimum it needs courier.ttf. If no TTF font can be found then DOSBox-X will print with the internal TTF font as used by the TrueType font output.

Windows host

DOSBox-X will first search for fonts in the FONTS subdirectory in the directory where your dosbox-x.exe is located. If the fonts cannot be found, then it will search for the system fonts, as follows:

Font file in FONTS directory Font file in system directory Notes

FONTS\courier.ttf

C:\Windows\Fonts\cour.ttf

FONTS\roman.ttf

C:\Windows\Fonts\times.ttf

FONTS\sansserif.ttf

C:\Windows\Fonts\arial.ttf

FONTS\ocra.ttf

C:\Windows\Fonts\Ocraext.ttf

Download Ocraext.ttf if not installed

FONTS\script.ttf

C:\Windows\Fonts\freescpt.ttf

Installed by MS Office

You are free to use suitable alternatives for these fonts, by copying them to the FONTS directory with file names mentioned in the first column of the above table. Moreover, DOSBox-X 0.83.4 and earlier will only search for font files in the FONTS directory.

Ocra (OCR-A) and Script (cursive) fonts may not be installed on your system. They are however rarely needed, and can typically be ignored. If you need them you may need to find those online.

Linux host

DOSBox-X will first search for fonts in the ~/.config/dosbox-x/FONTS directory. If the fonts cannot be found, then it will search for the fonts in the /usr/share/fonts directory, as follows:

Font file in FONTS directory Font file in system directory Notes

~/.config/dosbox-x/FONTS/courier.ttf

/usr/share/fonts/liberation-mono/LiberationMono-Regular.ttf

~/.config/dosbox-x/FONTS/roman.ttf

/usr/share/fonts/liberation-serif/LiberationSerif-Regular.ttf

~/.config/dosbox-x/FONTS/sansserif.ttf

/usr/share/fonts/liberation-sans/LiberationSans-Regular.ttf

~/.config/dosbox-x/FONTS/ocra.ttf

/usr/share/fonts/Ocraext.ttf

Download Ocraext.ttf if not installed

~/.config/dosbox-x/FONTS/script.ttf

/usr/share/fonts/freescpt.ttf

Download a Script (cursive) font

You are free to use suitable alternatives for these fonts, by copying them to the FONTS directory with file names mentioned in the first column of the above table. Moreover, DOSBox-X 0.83.4 and earlier will only search for font files in the FONTS directory.

Ocra (OCR-A) and Script (cursive) fonts may not be installed on your system. They are however rarely needed, and can typically be ignored. If you need them you may need to find those online.

Example: Print to file

In this example the output of DOS commands is simply redirected to the virtual LPT port, which in turn will be redirected to a text file.

Setup a DOSBox-X config file with the following lines:

[dosbox]
captures=capture

[parallel]
parallel1=file

No [printer] section is needed for this example.

Now start DOSBox-X, and type the following command:

DIR > LPT1

The above will cause a capture\dosbox_000.prt ASCII text file to be created. The exact save location is dependent on the captures= setting in the [dosbox] section.

You can also use this in most DOS programs, by selecting a generic text printer, or in Windows 2.x, 3.x, 95 or 98 by selecting the "Generic / Text Only" printer.

Note: If you booted real DOS, or Windows 9x in DOSBox-X the output filename will be guest os_000.prt instead.

You may be able to use this with a more advanced printer model selected in your DOS application, but the output will then have printer specific control codes in it. In addition, this may not work if the application expects to be able to have bi-directional communication with the printer.

Example: Printing to a real printer

Windows host, method 1

It will cause a Windows print dialogue to appear on the host, and you can print to any printer configured on the host, including print to PDF.

This method requires that you have first completed the FONT installation step above.

Make sure your DOSBox-X config file contains the statements:

[parallel]
parallel1=printer

[printer]
printer=true
printoutput=printer
timeout=1000

In DOSBox-X you can now simply redirect output to LPT1, or in DOS applications configure one of the printers listed above.

Windows host, method 2

This assumes you PC still has a parallel printer port integrated on the systemboard, or a legacy ISA printer adapter. It reportedly will not work with USB printer adapters or PCI printer port adapters.

Also note that the output is sent verbatim from the DOS application to the printer, without any filtering or conversion. Therefore it is important that the printer can understand the control codes that are being sent. In practice this means that this method is only really meant for situations where you have a legacy printer, or are perhaps only sending pure text.

Make sure your DOSBox-X config file contains the statements:

[parallel]
parallel1=file dev:lpt1

Alternatively you can try to set it up as follows, but this reportedly only works if your host is running Windows 9x, or with later Windows versions by installing "PortTalk"

[parallel]
parallel1=reallpt directlpt:378

Other alternatives are to install either WinPrint (Open Source), or DOSPRN, a Shareware application that specifically lists DOSBox-X as supported for printing to any printer configured on the Windows host system.

Linux host

First you need to give your Linux user access to the /dev/parport0 device, otherwise you will get permission denied errors. Replace "username" with your Linux username.

sudo usermod -a -G lp username

Now, similar to the Windows parallel printing instructions, try the following:

Make sure your DOSBox-X config file contains the statements:

[parallel]
parallel1=reallpt realport:/dev/parport0

This has been confirmed to work. Alternatively you can try to set it up as follows:

[parallel]
parallel1=file dev:/dev/parport0

But while this method seems to work on Windows, it does not seem to work properly on Linux.

Again, just like in the "Windows host, method 2" above, the output is sent verbatim to the printer, so the printer needs to be able to understand any control codes the DOS application sends.

Example: Print to PNG, BMP or PostScript

This method prints to a PNG, BMP or PostScript (PS) image file.

This method requires that you have first completed the FONT installation step above.

Make sure your DOSBox-X config file contains the statements:

[parallel]
parallel1=printer

[printer]
printer=true
printoutput=png
timeout=1000

The above example uses PNG, but you can simply change it to printoutput=bmp or printoutput=ps if you prefer. But note that BMP files will be much larger than PNG files, while the image quality will be identical.

In DOSBox-X you can now simply redirect output to LPT1, or in DOS applications configure one of the printers listed above.

The output will be saved as page1.png, page1.bmp or page1.ps in the current directory, and incremented if it already exists. Alternatively you can specify a different directory using the docpath= setting as documented above.

When using PostScript output, you can prevent a separate PostScript files from being generated for each page, by setting multipage=true.

Example: Redirect print output to a program on the host

In the [parallel] section for the parallel1-9 config options you can use the file option to direct the output to a file, which will then be opened by the specified application on the host.

The options available are:

  • openps:<program> start a program to open the file if the printer output is detected to be PostScript.

  • openpcl:<program> start a program to open the file if the printer output is detected to be PCL.

  • openwith:<program> start a program to open the file in all other conditions.

  • openerror:<program> start a program to open the file if an error had occurred.

e.g. when running DOSBox-X on a Windows host:

[parallel]
parallel1 = file file:output1.prn timeout:1000 openpcl:pcl6 openps:gswin32c openwith:notepad

This will cause any output to LPT1 to be written to output.prn, and if the output is determined to be PCL, it will be opened with a "pcl6" application, or if it is PostScript, it will be opened with GhostScript (gswin32c.exe), while for other filetypes it will be opened in notepad.

If you need to pass additional parameters to the application you can either enclose the command with quotes and add the parameters. e.g. openwith:"program arg1 arg2", the printer file will be added as a final parameter. If this is not flexible enough, for instance because you need to have the printer filename in the middle of other parameters, then create a shell script or batch file with a content similar to program arg1 %1 arg2, and call this shell script/batch file instead of the program directly.

Keep in mind that the output file will be created in your current working directory, if you don’t specify a path.

macOS example

In this example, it is assumed that your printing to a PostScript printer in your DOS application. The output is saved to a file on the host, and when the file is closed (when no output is received for 1 second), the file will be opened by the macOS Preview application such that it can be printed.

[parallel]
parallel1 = file file:~/Documents/output1.ps timeout:1000 squote openps:'open -s "Preview"'