Click here to Skip to main content
14,970,948 members
Articles / Multimedia / GDI+
Posted 1 Dec 2002


73 bookmarked

Crossing the bridge between Ghostscript and GDI+

Rate me:
Please Sign up or sign in to vote.
4.91/5 (32 votes)
1 Dec 20027 min read
A C++ wrapper for the Ghostscript DLL that enables to render PS directly to GDI+ Bitmap

Sample Image - ghostwrapper.png


This articles present a C++ interface for the Ghostscript DLL. Ghostscript[^] (GS) is a (very) famous interpretor for the Postscript language[^], it is used to render .ps files to a variety of image formats and printers. For the majority of case, using the gswin32.exe with command line parameters is good enough. However, someone might want to integrate GS into it's application with using gswin32.exe.

The solution could be using the C API interface to the DLL functions given by GS, however it is not suited for the (lazy) MSVC user: there are no available projects or workspace to use this API and you have to use make (an old UNIX souvenir) to rebuild the source (a nightmare).

To avoid all those problems, a C++ wrapper for the dll has been coded with the following features:

  • Dynamic loading of gsdll32.dll, by searching the path or the registry,
  • retrieving of all the C API methods in the dll
  • Intelligent class for the initialization of the Ghostscript engine,
  • make Ghostscript render to GDI+.
  • UNICODE compliant

Note that all the classes are documented with Doxygen.


Before getting into work, you may take a look at this quote from the Ghostscript licensing policy:

GNU Ghostscript may not be incorporated into commercial products which forbid copying or for which customers cannot obtain source code for no more than the cost of reproduction, although it may be distributed ("aggregated") with commercial products; AFPL Ghostscript may not be incorporated into commercial products at all, and may be distributed commercially only under extremely limited circumstances. However, Ghostscript is also available for commercial licensing, which in addition to the right to incorporate Ghostscript into commercial products includes support, a limited warranty, high-quality fonts, and other benefits. For more information about commercial licensing of Ghostscript, please contact our commercial distribution partner, the only entity legally authorized to distribute Ghostscript per se on any terms other than the GNU or AFPL licenses

So if you plan to use this wrapper in a commercial applications, take a look at the note on Commercial use.

Wrapper architecture

There are 2 main classes used to build the interface to gsdll32.dll:

  • CAPI is the interface to the gsdll32.dll. It handles dll loading/unloading, method retreiving and interface,
  • CAPISettings is used to set all the format output options, flags, display callbacks and other possible parameters of the ghostscript engine. Once this object is ready, it is used to start an engine.

Here's a brief description of the other classes:

Class nameDescription
CModuleLoad, unload ghostscript library
CAPIC API interface
CAPISettingsEngine initializer
CCallbackBase class for display callbacks
CGDIpCallbackGDI+ and ghostscript interface

All the classes are in the gsdll namespace. From now on, we will consider the following:

using namespace gsdll;
// ghostscript setting
CAPISettings settings;

Make sure Ghostscript is installed on your machine before trying to use this package (tested with AFPL Ghostscript 8.0).

Initializing Ghostscript with CAPISettings

The class CAPISettings is used to set-up the Ghostscript engine.

Output device

You can choose the device in the EDevice enumeration:

// setting JPEG output
settings.SetDevice( CAPISettings::DeviceJPEG);

Here are the main output devices among all the available:

  • DevicePNG16m, 24-bit PNG,
  • DeviceBMP16m, 24-bit BMP,
  • DeviceJPEG, JPEG,
  • DevicePDF, Adobe PDF writer
  • DeviceDisplay, custom ouput device (more details about this device below)

As mentionned aboce, the user can provide GS with a custom output device type. This type of device is used to make GS render to GDI+ Bitmap object and will be discussed later.

Output file

GS also allows you to control where it sends its output. With a display device this isn't necessary as the device handles presenting the output on screen internally. Some specialized printer drivers operate this way as well, but most devices are general and need to be directed to a particular file or printer.

To send the output to a file, use the SetOutputFile method. For instance, to direct all output into the file, use


When printing on MS Windows systems, output normally goes directly to the printer, PRN. When using GS as a file rasterizer (converting PostScript or PDF to a raster image format) you will of course want to specify an appropriately named file for the output.

GS also accepts the special filename '-' which indicates the output should be writtent to stardard output (the command shell).

Be aware that filenames beginning with the character have a special meaning in PostScript. If you need to specify a file name that actually begins with , you must prepend the os% filedevice explicitly. For example to output to a file named abc, you need to specify


Please see GS and the PostScript Language and the PostScript Language Reference Manual for more details on and filedevices. Note that on MS Windows systems, the character also has a special meaning for the command processor (shell), so you will have to double it.

Specifying a single output file works fine for printing and rasterizing figures, but sometimes you want images of each page of a multi-page document. You can tell GS to put each page of output in a series of similarly named files. To do this place a template '%d' in the filename which GS will replace with the page number.

You can also control the number of digits used in the file name:

'ABC-1.png', ... , 'ABC-10.png', ...
'ABC-001.pgm', ... , 'ABC-010.pgm', ...
'ABC_p0001.tiff', ... , 'ABC_p0510.tiff', ... , 'ABC_p5238.tiff'

Generally 03d is the best option for normal documents. As noted above, on MS Windows systems, you will have to double the character.

Miscellanous options

There are several option to control the raster quality:

  • SetResolution, sets the output resolution in dpi,
  • SetTextAlphaBits, controls the text sub-sampling,
  • SetGraphicAlphaBits, controls the text sub-sampling.

If rendering to JPEG, you can set the output quality from 0 (bad quality, good compression) to 100 (good quality, bad compression):


Custom options

There are plenty of available flags to control the output of GS. Some are implemented in the CAPISettings class, they will suit the basic needs. However, for the advanced user, it is possible to set custom arguments using AddCustomArgument:


Starting the engine:

Once you have set all the parameters, just build a CAPI instance using the CAPISettings object in the constructor:

// build and start GS api
CAPI gsapi( settings);
if (gsapi.IsInvalid())
	// the api was not properly initialized

Using the Ghostcript engine with CAPI

Once your CAPI instance has been built successfully, you have to feed it with Postscript. You can do that in numerous ways:

  • Sending an entire file:
  • Sending a string
    gsapi.RunString(_T("1 2 add == flush\n"));
    Note that you can specify the number of characters to be read.
  • Sending numerous strings:
    // prepare for receiving strings
    // sending string, the method RunStringContinue can be called several times
    gs.RunStringContinue(_T("more ps code"));
    // stop and render

When rasterizing, GS produces numerous messages (notification or error messages). These messages are redirected to 2 string streams (static members of CAPI):

// get the message output buffer of GS
// get the message error buffer of GS

Implementing your own ouput device with CCallback

As mentioned above, it is possible to implement your own output device. This is made by furnishing GS with a series of function callbacks. In order to help the user, these callbacks have been encapsulated into a virtual base class: CCallback .

In order to write your own device, you must derive a class from CCallback and implement all the following virtual functions:

int Open(...)New device has been opened.
int PreClose(...)Device is about to be closed.
int Close(...)Device has been closed.
int PreSize(...)Device is about to be resized.
int Size(...)Device has been resized. New pointer to raster returned argument.
int Sync(..)flushpage
int Page(...)Showpage If you want to pause on showpage, then don't return immediately.
DWORD GetFormat() constreturns the display format

Here a snipet to attach your custom device to GS:

// a custom display callback inherited from CCallback
CMyCustomCallback callback;
// attaching to GS

I will not go more into details about the use of those functions. For the interrested user, the creation of a custom output device is illustrated with CGDIpCallback which implements the outputing to GDI+ Bitmap.

Crossing the bridge between GS and GDI+: CGDIpCallback

This class implements the necessary callback in order to have a output device to GDI+.

When the callback Size is called, the address of the raster buffer is stored and a Bitmap is created with the appropriate dimensions.

After that, when Page is called, the raster is blitted into the Bitmap. Each time Page is called, the bitmap is stored in a bitmap list for later use. These bitmaps can be accessed using GetBitmapContainer:

CGDIpCallback callback;
// processing and rendering
// iterating the produced bitmaps:
CGDIpCallback::BitmapContainer& bc=callback.GetBitmapContainer();
CGDIpCallback::BitmapContainer::iterator it;
for (it=bc.begin(); it!=bc.end();++it)
	Bitmap* pBitmap=*it;
	// working on bitmap


The GS dll accepts only 1 instance running in the same thread. Hence, once an engine is started, no other can be build successfully until it is destroyed.

Demo project

The demo project is Postscript engine. Enter some postscript code and raster, if successful, the result is displayed in the dialog window.


[1] Ghostscript web site
[2] PostScript® Language Reference, Third Edition

Update history

  • 2-11-2002,
    • Added UNICODE support
    • Better DLL search in CModule. Thanks to Russel Lang from
    • Added licensing policy
  • 2-11-2002, initial release.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Jonathan de Halleux
United States United States
Jonathan de Halleux is Civil Engineer in Applied Mathematics. He finished his PhD in 2004 in the rainy country of Belgium. After 2 years in the Common Language Runtime (i.e. .net), he is now working at Microsoft Research on Pex (

Comments and Discussions

QuestionPDF to png Pin
TrongTran12-Oct-15 5:56
MemberTrongTran12-Oct-15 5:56 
QuestionThere is a C# version of the interpreter if anyone needs it. Pin
Josip.Habjan27-Aug-13 19:48
MemberJosip.Habjan27-Aug-13 19:48 
QuestionCapture GDI messages Pin
abc_nus_student27-Nov-07 14:18
Memberabc_nus_student27-Nov-07 14:18 
GeneralAddCustomArgument unicode error Pin
htfgytr764564517-Jul-07 5:17
Memberhtfgytr764564517-Jul-07 5:17 
GeneralAddCustomeArgument doesn't work Pin
Harald Geißelhart6-Jul-07 7:43
MemberHarald Geißelhart6-Jul-07 7:43 
GeneralC# version Pin
illium12-Mar-07 1:02
Memberillium12-Mar-07 1:02 
GeneralRe: C# version Pin
Telsum18-May-07 19:46
MemberTelsum18-May-07 19:46 
GeneralRe: C# version Pin
illium27-May-07 12:54
Memberillium27-May-07 12:54 
GeneralRe: C# version Pin
humble.apprentice12-Nov-07 22:10
Memberhumble.apprentice12-Nov-07 22:10 
GeneralRe: C# version Pin
illium15-Nov-07 10:43
Memberillium15-Nov-07 10:43 
GeneralRe: C# version Pin
illium15-Nov-07 14:38
Memberillium15-Nov-07 14:38 
GeneralRe: C# version Pin
Marshall16-Nov-07 8:03
MemberMarshall16-Nov-07 8:03 
GeneralRe: C# version Pin
illium16-Nov-07 10:41
Memberillium16-Nov-07 10:41 
GeneralPDF to PS Pin
wick#320-Nov-06 21:58
Memberwick#320-Nov-06 21:58 
QuestionI Need bmp display with ZoomIn and ZoomOut options. Pin
PrabhakaranYok30-Oct-06 7:01
MemberPrabhakaranYok30-Oct-06 7:01 
GeneralLoad PDF from URL Pin
rombonobo28-Sep-06 6:06
Memberrombonobo28-Sep-06 6:06 
GeneralCAPI::IsInvalid() Error ininitialization API Pin
bidalah14-Apr-06 10:15
Memberbidalah14-Apr-06 10:15 
GeneralRe: CAPI::IsInvalid() Error ininitialization API Pin
bidalah14-Apr-06 11:58
Memberbidalah14-Apr-06 11:58 
QuestionHelp with simple usage Pin
ricecake7-Feb-06 9:25
Memberricecake7-Feb-06 9:25 
AnswerRe: Help with simple usage Pin
ricecake7-Feb-06 10:04
Memberricecake7-Feb-06 10:04 
Generalbug report and my patch about m_iLastStatus error Pin
bigbencat5-Jan-06 14:18
Memberbigbencat5-Jan-06 14:18 
GeneralBug in CAPI::IsInvalid Pin
srettig15-Oct-05 0:17
Membersrettig15-Oct-05 0:17 
GeneralDisplaying PDF files with GDI+ Pin
rombonobo9-Aug-05 23:48
Memberrombonobo9-Aug-05 23:48 
GeneralRe: Displaying PDF files with GDI+ Pin
Igor Tolmachev28-Mar-06 21:31
MemberIgor Tolmachev28-Mar-06 21:31 
Generalpdf2whatever location Pin
vaz4-Aug-05 7:17
Membervaz4-Aug-05 7:17 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.