Skip to content

Guide:Setting up printing in DOSBox‐X

Jump to bottom
Wengier edited this page Jun 1, 2021 · 71 revisions

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. It also has partial support for the IBM Pro Printer, where the control codes do not conflict with the Epson control codes.

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 (limited function)

  • 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

  • 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: printer

  • 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 the LPT1 port.

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

Note
 The original IBM PC with MDA or Hercules graphics card had the first printer port configured on IO base address 0x3BC, and 0x378 would then become LPT2. This is not emulated (see Wikipedia).
Note
 Unlike on a typical retro PC, the emulated parallel port does not use an IRQ. Therefore there is no resource conflict if the emulated SoundBlaster is configured for IRQ 7.

disabled

  • Disables the printer port emulation

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

reallpt

  • Windows:

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

      • Default: 378

    • ecpbase (base IO 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

Send to a printer. This has it’s own configuration section which is documented 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 on IO base address 0x3BC.

parallel4-9

  • Default value: disabled

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

Note
 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 recommended 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: printer

  • Possible values: png, ps, bmp, printer

printer

To send the output to a printer in Windows. A print dialogue will appear. You can specify the target printer with the device option.

png or bmp

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

ps

PostScript, which is the best option typically for Linux and macOS hosts as it supports multipage documents and can easily be converted to PDF.

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.

device

  • Default value: -

  • Possible values: - or device name or number

Only applicable if printoutput=printer.

The default value will cause you to get asked for the printer the first time you print after starting DOSBox-X. You can alternatives specify the printer device name (or a partial name) or the device number. From a consistency perspective it is best to specify a device name, as the device number can change due to devices being added or removed.

To see the list of available devices, start DOSBox-X and open the DOS menu, followed by "List printer devices".

Example:

[parallel]
parallel1=printer

[printer]
printoutput=printer
device="Microsoft Print to PDF"

docpath

  • Default value: .

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

fontpath

  • Default value: FONTS

The path (directory) where the TTF fonts (courier.ttf, ocra.ttf, roman.ttf, sansserif.ttf, script.ttf) are stored. Defaults to the FONTS subdirectory in the current working directory (or where the DOSBox-X executable is located).

printdbcs

  • Default value: auto

  • Possible values: true, false, auto

Allows DOSBox-X to print Chinese/Japanese/Korean DBCS (double-byte) characters when a DBCS code pages (932: Japanese, 936: Simplified Chinese; 949: Korean; 950: Traditional Chinese) is active. If set to auto (default), this is enabled only for the TrueType font (TTF) output with the DBCS support enabled.

openwith

  • Default value: \<blank\>

Start the specified program to open the output file.

If set, the command window will be hidden for openwith/openerror options on the Windows platform.

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.

shellhide

  • Default value: false

  • Possible values: true, false

If set, the command window will be hidden for openwith/openerror options. Only supported in the Windows platform.

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. If you use the TrueType font output, then the TTF font that is currently active on the screen will automatically be used for printing as well if the ttf.printfont option (in [render] section) is enabled (default) as of DOSBox-X version 0.83.14.

If no TTF font can be found then DOSBox-X will print with the internal (default) TTF font as used by the TrueType font output.

Windows host

DOSBox-X will first search for fonts in the FONTS subdirectory in the current working directory or 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 (or FONTS subdirectory in the current working 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.

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

[parallel]
parallel1=printer

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

In DOSBox-X you can now simply redirect output to LPT1, or in DOS applications configure one of the printers listed above. The printer dialogue will show up once when a printer selection is made. If you want the printer dialogue to show up every time for printing to LPT1, please leave the "device" empty.

Windows host, method 2

This assumes you PC still has a parallel printer port integrated on the system board, 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

Windows host, in combination with 3rd-party printing solution

In addition to relying entirely on the built-in printing methods, DOSBox-X can also work in combination with external third-party printing solutions like Printfil, DOSPRN, or WinPrint (open-source). Both Printfil and DOSPRN are shareware applications that specifically list DOSBox-X as supported for printing to any printer configured on the Windows host system.

Windows host, extended solution using Printfil

According to its description, Printfil allows text-based applications to print to any Windows printer, including USB, network printers, fax modems and PDF writers, without any changes to the original applications. You can set your application to print to an ASCII file, or have Printfil capturing a parallel port (PRN: and from LPT1: to LPT9:) or serial port (from COM1: to COM9:), automatically redirecting your print jobs to any printer.

Printfil has implemented official support for integration with DOSBox-X since version 5.27. In addition to automatic printer handling via printing ports, it also supports additional features such as print preview, background image inclusion, text colorization, direct PDF and emailing. You can find the main features of Printfil in its feature list page. Once configured, there is no additional setup needed for printing support on the DOSBox-X side.

You can select the port to capture (e.g. LPT1) and the printer to use (e.g. Microsoft Print to PDF) from its configuration window. Printfil will automatically detect DOSBox-X if it is installed in the default path (C:\DOSBox-X), and ask whether to capture the selected port for DOSBox-X. If you answer Yes, then the specified printing port(s) will be automatically captured in future DOSBox-X sessions. Below is a screenshot of its configuration window.

The Printfil configuration window

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.

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"'
Clone this wiki locally