Skip to content

Latest commit

 

History

History
747 lines (530 loc) · 28.8 KB

Guide:Setting-up-printing-in-DOSBox‐X.asciidoc

File metadata and controls

747 lines (530 loc) · 28.8 KB
Raw

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].

[parallel] section options

This section lists the available configuration options for the [parallel] section that DOSBox-X provides. They are used to configure the virtual parallel ports provided inside DOSBox-X.

Note
 It is possible to modify parallel port settings directly from the DOSBox-X DOS prompt with either the parallel or config -set parallel commands. Any settings you modify this way are however lost when you restart DOSBox-X.

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 when 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

  • Additional Windows options:

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

      • Default: 378

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

  • Additional Linux options:

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

Used to specify that you want to redirect the output to a real physical port on the host PC. You will need to use this if you have for instance a parallel port security dongle, but can be used with any parallel device supported by your dos application.

Note
 This option may not work without additional steps, as this tries to do direct access to the port on the host PC, which modern operating systems will block by default.

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 instead 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 an emulated Epson dot-matrix printer. This has its 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 of the DOSBox-X config file.

Only one Epson 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 if you intend to print text.

The Virtual Printer option emulates a 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.

Generally speaking when looking through the list of supported printers in a DOS application, look for any Epson printer. Epson itself suggested in some of their literature to look for printers in the following order for backward compatibility

  • LQ Series - Letter Quality 24-pin

    • B/W - LQ-870, LQ-570/570+, LQ-850+, LQ-850, LQ-510/550, LQ-200, LQ-500, LQ-2550, LQ-2500, LQ-800, LQ-1500

    • Colour - LQ-860+, LQ-860

    • Wide B/W - LQ-2180, LQ-2170/2070, LQ-1070/1070+, LQ-1170, LQ-1050+, LQ-1050, LQ-1010, LQ-1000, LQ-1500

    • Wide Colour - LQ-2550, LQ-2500

  • FX Series

    • B/W - FX-880, FX-870, FX-850, FX-800, FX-85, FX-80+, FX-80

    • Wide B/W - FX-2180, FX-2170, FX-1180, FX-1170, FX-1050, FX-1000, EX-1000, FX-105, FX-100+, FX-100

  • LX Series

    • B/W - LX-300, LX-810/850, LX-800, LX-80/86

    • Wide B/W - LX-1050+, LX-1050

  • EX Series

    • B/W - EX-800

    • Wide B/W - EX-1000

  • RX Series

    • B/W - RX-80

  • MX Series

    • B/W - MX-85, MX-82, MX-80

Note
 It is possible to modify emulated printer settings directly from the DOSBox-X DOS prompt with the config -set printer commands. Any settings you modify this way are however lost when you restart DOSBox-X.
Note
 If you’re wanting to print in landscape on US Letter or A4 paper, or in portrait on A3 paper, select a wide printer in your DOS application, as otherwise the software may not give you the possibility to configure the paper properly.
Note
 For printing in text mode it should not matter which Epson printer is selected, as DOSBox-X will use TrueType Fonts to render the text at the selected DPI. As such for text mode printing, it does not matter if a 9 or 24-pin printer is selected.
Warning
 Printing to any Epson 24-pin printer in "360 x 180" or "360 x 360" mode results in corrupted output. In addition, models that should support colour output like the LQ-860/2500/2550 instead print in B/W. These appear to be issues with the Epson printer emulation.

Features:

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

  • Graphics printing for 24-pin (LQ series) and 48-pin (DLQ series) modes supported, up to 360dpi

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

  • Some older non-conflicting IBM control codes are supported

Limitations:

  • 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 rasterising 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

printer

  • Default value: false

  • Possible values: true, false

Enables or disables Epson virtual printer emulation.

dpi

  • Default value: 360

  • Possible values: 0-65535

Sets the dots-per-inch of the Epson virtual printer.

width

  • Default value: 85

  • Possible values: 0-65535

Width of paper in 1/10 inch for the Epson virtual printer. The default of 85 corresponds to 8.5".

Example of the width of some standard paper sizes:

Paper Orientation Official size DOSBox-X width setting

US Letter

Portrait

8.5"

85

US Letter

Landscape

11.0"

110

US Legal

Portrait

8.5"

85

US Legal

Landscape

14.0"

140

A3

Portrait

297mm

116

A3

Landscape

420mm

165

A4

Portrait

210mm

82

A4

Landscape

297mm

116

A5

Portrait

148mm

58

A5

Landscape

210mm

82
Note
 Paper width for real Epson printers is limited to 257mm (10.1") for regular models and 420mm (16.5") for wide carriage models.

height

  • Default value: 110

  • Possible values: 0-65535

Height of paper in 1/10 inch for the Epson virtual printer. The default of 110 corresponds to 11.0" (US Letter).

Example of the height of some standard paper sizes:

Paper Orientation Official size DOSBox-X height setting

US Letter

Portrait

11.0"

110

US Letter

Landscape

8.5"

85

US Legal

Portrait

14.0"

140

US Legal

Landscape

8.5"

85

A3

Portrait

420mm

165

A3

Landscape

297mm

116

A4

Portrait

297mm

116

A4

Landscape

210mm

82

A5

Portrait

210mm

82

A5

Landscape

148mm

58

printoutput

  • Default value: printer (windows host), else png

  • Possible values: png, ps, bmp, printer

Output option for the Epson virtual printer. Various output options are available:

printer

To send the output to a printer on a Windows host. The Windows host print dialogue will appear when you print from a DOS application. You can specify the default target printer with the device= option.

png or bmp

Create a PNG or BMP file with the print output.

Between PNG and BMP, PNG is a more modern format. BMP will create larger files, due to lack of compression, while the image quality will be identical.

ps

Create a PostScript output file, and supports multi-page documents with the multipage= option.

This is typically the best option for Linux and macOS hosts (prior to Ventura), as PostScript is supported by default. For Windows, and newer macOS hosts it requires installing a PostScript viewer.

This format can easily be converted to PDF.

multipage

  • Default value: false

  • Possible values: true, false

Only applicable if printoutput=ps.

Adds all pages printed to the virtual Epson printer to one PostScript file until either a timeout, or until CTRL-F2 is pressed. See also the timeout= option below.

device

  • Default value: -

  • Possible values: - or device name or number

Only applicable on Windows hosts and when printoutput=printer.

The default value will cause you to get asked for the printer the first time you print to the virtual Epson printer after starting DOSBox-X. Any subsequent prints will go to the same printer, until DOSBox-X is restarted.

You can use this option to 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 on the host.

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 to be stored. Defaults to the current working directory.

fontpath

  • Default value: FONTS

The path (directory) where the TrueType 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).

TrueType fonts are used when printing text to the virtual Epson printer. They are not used when printing in graphics mode.

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.

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

Some other 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

  • 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 on the Windows platform.

timeout

  • Default value: 0

  • Possible values:

Timeout (in milliseconds). Set to 1000 for a 1-second timeout.

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

Since not all DOS applications will send a form-feed, especially if you’re 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. If the printout gets split over multiple files, increase this value.

You can also manually send a form-feed, by pressing CTRL-F2 or using the form-feed option 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).

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 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.

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 a 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.

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 a DOS command or application is simply redirected to the virtual LPT port in DOSBox-X, which in turn will be redirected to a file on the host.

This is useful if you’re printing just simple text, as the file on the host will contain the exact text.

If the application expects a printer that can do more than just simple text, and sends control codes for that printer, the file will also contain those control codes.

This can actually be useful, if you select a PostScript or HP PCL printer in the DOS application, as the resulting file will be a PostScript or HP PCL file which can be opened on the host with an appropriate application.

In this example, set up a DOSBox-X config file with the following lines:

[dosbox]
captures=capture

[parallel]
parallel1=file

No [printer] section is needed for this example, as we are not emulating a printer.

Now start DOSBox-X, and on the DOSBox-X command prompt 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.

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

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 Epson printers listed above. The printer dialogue will show up after a printer selection is made. If you want the printer selection 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 has a legacy ISA parallel printer adapter. It reportedly will not work with either USB parallel printer adapters or PCI parallel 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 printer control codes that are being sent by the application. 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 only works if your host is running Windows 9x, or with later Windows versions by installing "PortTalk". PortTalk is needed because direct port access is no longer permitted with more modern Windows versions. The last Windows version supported by PortTalk is Windows XP (32-bit).

[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 parallel printer port on the Linux host, otherwise you will get permission denied errors.

Replace "username" in the example below with your own Linux username. This will make your user a member of the "lp" group, which is a group that on most (all?) Linux distributions should have the necessary access to the parallel port.

sudo usermod -a -G lp username

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 using this later method seems to work on Windows, according to one report, it does not seem to work properly on Linux.

The output is sent verbatim to the printer, so the printer needs to be able to understand any control codes the DOS application sends.

Note
 In the case of a real parallel port, the first port will be /dev/parport0, but in the case of a USB parallel port adapter it will be /dev/usblp0, but it is unclear if a USB parallel port adapter will work.
Note
 On Linux there has been some success with using a StarTech PEX1P2 PCIe parallel port adapter. But it is necessary to first do a modprobe parport_pc which will create the necessary /dev/parport0 device.

Example: Print to PNG or BMP

This method prints to a PNG or BMP 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 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 or page1.bmp in the current directory, and incremented if it already exists. Alternatively you can specify a different directory using the docpath= setting as documented above.

Example: Print to PostScript

This method prints to a PostScript (PS) image file, which can be easily converted to PDF.

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

[parallel]
parallel1=printer

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

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.ps in the current working directory, and incremented if it already exists. Alternatively you can specify a different directory using the docpath= setting as documented above.

The multipage=true setting is specific to PostScript output, and prevents a separate PostScript file from being generated for each printed page.

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 can then optionally be opened by the specified application on the host. This application can then be used to view the output, and possibly print it or be used to convert the output to something like PDF with a PDF printer.

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 HP 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:output.prn timeout:2000 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.

Linux PostScript printing example

In this example, it is assumed that you’re printing to a PostScript printer in your DOS application. This should give you the highest quality output, and depending on the application, you may even get colour by selecting a colour PostScript printer. The output is saved to a file on the host, to the directory specified with the captures= option, and when the file is closed (when no output is received for 2 seconds), the file will be opened using xdg-open such that it can be viewed and printed.

[dosbox]
captures=capture

[parallel]
parallel1=file file:output.ps timeout:2000 openps:xdg-open

macOS PostScript printing example

Similar to the Linux example above, but here the macOS Preview application is used to open the PostScript file, from where it can be viewed and printed.

Note
 Support for PostScript was removed from the macOS Preview application in the macOS Ventura (13) release. It is still possible to drag a PostScript file to the printer icon in macOS Ventura, but this support was also removed in macOS Sonoma (14). 
[dosbox]
captures=capture

[parallel]
parallel1=file file:output.ps timeout:2000 squote openps:'open -s "Preview"'