While multiple versions of GraphicsMagick may be installed at one time, if your intention is to replace a prior installation of GraphicsMagick with a newer version, then it may be wise to uninstall the existing GraphicsMagick (see uninstall procedure) prior to installing the newer version.

While it is not a requirement, it is strongly recommended that the Ghostscript package (GraphicsMagick is tested with version 8.70) be installed. GraphicsMagick uses Ghostscript to render Postscript and PDF files, as well as formats where a translator to Postscript is available. GraphicsMagick will also use the fonts delivered with Ghostscript to support the standard set of Adobe Postscript fonts like "Helvetica" and "Times Roman" if these fonts are not available as TrueType fonts.

The installation package includes the GraphicsMagick Perl extension ( PerlMagick <perl.html>) as an installation option. If you would like to use this extension, then you must install ActiveState ActivePerl prior to commencing with installation of GraphicsMagick.

Retrieve the GraphicsMagick Windows binary install package from a one of the ftp sites listed at the GraphicsMagick Download Sites page. The available install packages are as follows

Windows Dynamic-Multithread (DLL-based) install package with utilities, PerlMagick, ImageMagickObject COM object, and web pages:

GraphicsMagick-1.3-Q8-windows-dll.exe
GraphicsMagick-1.3-Q16-windows-dll.exe

Note that the QuantumDepth=8 version (Q8) which provides industry standard 24/32 bit pixels consumes half the memory and about 30% less CPU than the QuantumDepth=16 version (Q16) which provides 48/64 bit pixels for high-resolution color. A Q8 version is fine for processing typical photos intended for viewing on a computer screen. If you are dealing with film, scientific, or medical images, use ICC color profiles, or deal with images that have limited contrast, then the Q16 version is recommended.

A screen is displayed which presents most (or all) of the following options:

• Create a desktop icon
• Update executable search path
• Associate supported file extensions with GraphicsMagick
• Install PerlMagick for ActiveState Perl v5.8.7 build 815
• Install ImageMagickObject OLE Control for VBscript, Visual Basic, and WSH.

"Creating a desktop icon" and "Update the executable search path" are selected by default. The remaining options default to un-selected. Select the options you prefer. Note that ActiveState Perl packages are intended to be binary compatible across a build series (i.e. 800 series builds should be binary compatible).

Think twice before selecting "Associate supported file extensions with GraphicsMagick" since this will set up approximately fifty file associations, including common formats like JPEG, GIF, PNG, TIFF, and PDF. These file associations will be to the 'gmdisplay' program which is suitable for displaying images, but currently offers little more than that. Windows XP seems to handle the file associations pretty well, allowing you to choose from a list of programs, but older systems like Windows NT 4.0 and Windows '98 only support a single association per format, which can be quite annoying. Associations for GraphicsMagick's native formats (such as MIFF) will always be made.

Once you have made your selections, click on "Next>" to continue.

By default "View GraphicsMagick.html" is check-marked. This causes the GraphicsMagick web pages to be displayed in your web browser when "Finish" is selected. If you do not want to view the web pages, then de-select "View GraphicsMagick.html". Select "Finish" to exit the installation program.

Under Windows '95 and Windows '98 it will be necessary to reboot the system in order for some settings to take effect (such as executable search path) since these are set in autoexec.bat. Please verify that autoexec.bat is updated correctly. We have received some reports that the path in autoexec.bat is not always updated correctly.

Select "Command Prompt" from the Windows Start menu. Within the window type

gm convert logo: logo.miff
gmdisplay logo.miff

and the GraphicsMagick logo should be displayed in a window.

The GraphicsMagick package incorporates its own uninstall functionality. Always remove an installed GraphicsMagick via its uninstall function since manually removing it (such as by removing its installation directory) will leave behind the registry entries and path settings established at install time.

Under Windows '95 and Windows '98, use the "Uninstall" entry in the GraphicsMagick portion of the Windows start menu to initiate the uninstall.

On NT 4.0 and 5.X -based systems, GraphicsMagick should be removed via the "Add or Remove Programs" area of the Windows Control Panel. Select the GraphicsMagick package from the list, and click on "Change/Remove" to uninstall it.

The GraphicsMagick gm utility may be executed as a sub-process by other programs. If gm utility is not in the systems executable search path (it should be since the GraphicsMagick install extends the path), then the utility should be executed via the complete path to the executable.

The ImageMagickObject COM object may be used to execute the gm sub-functions (e.g. "convert") without spawning a new process or causing Windows to pop up a window. The COM object supports multi-threaded concurrent use.

When GraphicsMagick is installed, entries are added to the Windows Registry so that other programs may obtain information regarding the most recently installed GraphicsMagick. These entries are available under the registry path HKEY_LOCAL_MACHINE\SOFTWARE\GraphicsMagick\Current.

These registry keys are currently available:

The Visual C++ distribution targeted at Windows XP, Win2K, or Windows 98 does not provide any stock workspace (DSW) or project files (DSP) except for those included with third party libraries. Instead, there is a "configure" program that must run to create build environments to satisfy various requirements.

The Visual C++ system provides three different types of "runtimes" that must match across all application, library, and DLL code that is built. The "configure" program creates a set of build files that are consistent for a specific runtime selection.

The three options for runtime support are:

1. Dynamic Multi-threaded DLL runtimes (VisualDynamicMT).
2. Static Single-threaded runtimes (VisualStaticST).
3. Static Multi-threaded runtimes (VisualStaticMT).
4. Static Multi-threaded DLL runtimes (VisualStaticMTDLL).

In addition to these runtimes, the VisualMagick build environment allows you to select whether to include the X11 libraries in the build or not. X11 DLLs and headers are provided with the VisualMagick build environment. Most Windows users do not use X11 so they will prefer to build without X11 support. When X11 is not supported, gm subcommands 'animate', 'display', and 'import' will not work.

This leads to five different possible build options, which should cover almost any particular situation. The default binary distribution is built using #1 from above with the X11 libraries included. This results in an X11 compatible build using all DLL's for everything and multi-threaded support (the only option for DLL's).

To do a build for your requirements, simply go to the configure sub- directory under VisualMagick and open the configure.dsw workspace (for Visual C++ 6.0) or configure.sln (for Visual C++ 7.X or 8.X). Set the build configuration to "Release" under the

"Build..., Set Active Configuration..." menu.

Build and execute the configure program and follow the on-screen instructions. You should not change any of the defaults unless you have a specific reason to do so.

The configure program provides a button entitled

Edit "magick_config.h"

Clicking this button brings up magick_config.h in Windows notepad for optionally changing any preprocessor defines in GraphicsMagick's magick_config.h file. This file is copied to magick\magick_config.h. You may safely open magick\magick_config.h, modify it, and recompile without re-running the configure program. In fact, using notepad to edit the copied file may be preferable since it preserves the original magick_config.h file.

Key user tunables in magick_config.h include:

QuantumDepth (default 8)

Specify size of PixelPacket color Quantums (8, 16, or 32) A value of 8 uses half the memory than 16 and may run 30% faster, but provides 256 times less color resolution than a value of 16.

UseInstalledMagick (default undefined)

Define to build a GraphicsMagick which uses registry settings or embedded paths to locate installed components (coder modules and configuration files). The default is to look for all files in the same directory as the executable.

ProvideDllMain (default undefined)

Define to include a DllMain() function ensures that the GraphicsMagick DLL is properly initialized without participation from dependent applications. This avoids the requirement to invoke IntializeMagick() from dependent applications but only works for DLL builds.

After creating your build environment you can proceed to open the DSW (or SLN) file that was generated in the VisualMagick directory and build everything from there.

In the final DSW file you will find a project call "All". In order to build everything in the distribution, select this project and make it the "active" project. Set the build configuration to the desired one (Debug, or Release) and do a "clean" followed by a "build". You should do the build in a specific way:

1. Make the "All" project the active project (Bold) Right click on the All project and select "Set As Active Project"
2. Select "Build..., Clean"
3. Select "Build..., Build"
4. Go get some coffee unless you have a very fast machine!.

The "Clean" step is needed in order to make sure that all of the target support libraries are updated with any patches needed to get them to compile properly under Visual C++.

All of the required files that are needed to run any of the command line tools will be found in the "bin" subdirectory of the VisualMagick subdirectory. This includes EXE, and DLL files. You should be able to test the build directly from this directory without having to move anything to any of the global SYSTEM or SYSTEM32 areas in the operating system installation.

Note #1:

The Visual C++ distribution of GraphicsMagick comes with the Magick++ C++ wrapper by default. This add-on layer has a large number of demo and test files that can be found in GraphicsMagick\Magick++\demo, and GraphicsMagick\Magick++\tests. There are also a variety of tests that use the straight C API as well in GraphicsMagick\tests.

All of these programs are NOT configured to be built in the default workspace created by the configure program. You can cause all of these demos and test programs to be built by checking the box in configure that says:

"Include all demo and test programs"

In addition, there is another related checkbox (checked by default) that causes all generated project files to be created standalone so that they can be copied to other areas of you system.

This is the checkbox:

"Generate all utility projects with full paths rather then relative paths"

WOW - that a mouthfull - eh?

Visual C++ uses a concept of "dependencies" that tell it what other components need to be build when a particular project is being build. This mechanism is also used to ensure that components link properly. In my normal development environment, I want to be able to make changes and debug the system as a whole, so I like and NEED to use dependencies. However, most end users don't want to work this way.

Instead they really just want to build the package and then get down to business working on their application. The solution is to make all the utility projects (UTIL_xxxx_yy_exe.dsp) use full absolute paths to all the things they need. This way the projects stand on their own and can actually be copied and used as templates to get a particular custom application compiling with little effort.

With this feature enabled, you should be able to nab a copy of...

VisualMagick\utilities\UTIL_convert_xxx_exe.dsp (for C)

-or-

VisualMagick\Magick++\demo\UTIL_demo_xxx_exe.dsp (for C++)

... and pop it into notepad, modify it (carefully) to your needs and be on your way to happy compiling and linking.

You can feel free to pick any of the standard utilities, tests, or demo programs as the basis for a new program by copying the project and the source and hacking away.

The choice of what to use as a startreen is displayed which presents most (or all) of the following options:

• Create a desktop icon
• Update executable search path
• Associate supported file extensions with GraphicsMagick
• Install PerlMagick for ActiveState Perl v5.8.7 build 815
• Install ImageMagickObject OLE Control for VBscript, Visual Basic, and WSH.

"Creating a desktop icon" and "Update the executable search path" are selected by default. The remaining options default to un-selected. Select the options you prefer. Note that ActiveState Perl packages are intended to be binary compatible across a build series (i.e. 800 series builds should be binary compatible).

Think twice before selecting "Associate supported file extensions with GraphicsMagick" since this will set up approximately fifty file associations, including common formats like JPEG, GIF, PNG, TIFF, and PDF. These file associations will be to the 'gmdisplay' program which is suitable for displaying images, but currently offers little more than that. Windows XP seems to handle the file associations pretty well, allowing you to choose from a list of programs, but older systems like Windows NT 4.0 and Windows '98 only support a single association per format, which can be quite annoying. Associations for GraphicsMagick's native formats (such as MIFF) will always be made.

Once you have made your selections, click on "Next>" to continue.

By default "View GraphicsMagick.html" is check-marked. This causes the GraphicsMagick web pages to be displayed in your web browser when "Finish" is selected. If you do not want to view the web pages, then de-select "View GraphicsMagick.html". Select "Finish" to exit the installation program.

Under Windows '95 and Windows '98 it will be necessary to reboot the system in order for some settings to take effect (such as executable search path) since these are set in autoexec.bat. Please verify that autoexec.bat is updated correctly. We have received some reports that the path in autoexec.bat is not always updated correctly.

Select "Command Prompt" from the Windows Start menu. Within the window type

gm convert logo: logo.miff
gmdisplay logo.miff

and the GraphicsMagick logo should be displayed in a window.

The GraphicsMagick package incorporates its own uninstall functionality. Always remove an installed GraphicsMagick via its uninstall function since manually removing it (such as by removing its installation directory) will leave behind the registry entries and path settings established at install time.

Under Windows '95 and Windows '98, use the "Uninstall" entry in the GraphicsMagick portion of the Windows start menu to initiate the uninstall.

On NT 4.0 and 5.X -based systems, GraphicsMagick should be removed via the "Add or Remove Programs" area of the Windows Control Panel. Select the GraphicsMagick package from the list, and click on "Change/Remove" to uninstall it.

The GraphicsMagick gm utility may be executed as a sub-process by other programs. If gm utility is not in the systems executable search path (it should be since the GraphicsMagick install extends the path), then the utility should be executed via the complete path to the executable.

The ImageMagickObject COM object may be used to execute the gm sub-functions (e.g. "convert") without spawning a new process or causing Windows to pop up a window. The COM object supports multi-threaded concurrent use.

When GraphicsMagick is installed, entries are added to the Windows Registry so that other programs may obtain information regarding the most recently installed GraphicsMagick. These entries are available under the registry path HKEY_LOCAL_MACHINE\SOFTWARE\GraphicsMagick\Current.

These registry keys are currently available:

The Visual C++ distribution targeted at Windows XP, Win2K, or Windows 98 does not provide any stock workspace (DSW) or project files (DSP) except for those included with third party libraries. Instead, there is a "configure" program that must run to create build environments to satisfy various requirements.

The Visual C++ system provides three different types of "runtimes" that must match across all application, library, and DLL code that is built. The "configure" program creates a set of build files that are consistent for a specific runtime selection.

The three options for runtime support are:

1. Dynamic Multi-threaded DLL runtimes (VisualDynamicMT).
2. Static Single-threaded runtimes (VisualStaticST).
3. Static Multi-threaded runtimes (VisualStaticMT).
4. Static Multi-threaded DLL runtimes (VisualStaticMTDLL).

In addition to these runtimes, the VisualMagick build environment allows you to select whether to include the X11 libraries in the build or not. X11 DLLs and headers are provided with the VisualMagick build environment. Most Windows users do not use X11 so they will prefer to build without X11 support. When X11 is not supported, gm subcommands 'animate', 'display', and 'import' will not work.

This leads to five different possible build options, which should cover almost any particular situation. The default binary distribution is built using #1 from above with the X11 libraries included. This results in an X11 compatible build using all DLL's for everything and multi-threaded support (the only option for DLL's).

To do a build for your requirements, simply go to the configure sub- directory under VisualMagick and open the configure.dsw workspace (for Visual C++ 6.0) or configure.sln (for Visual C++ 7.X or 8.X). Set the build configuration to "Release" under the

"Build..., Set Active Configuration..." menu.

Build and execute the configure program and follow the on-screen instructions. You should not change any of the defaults unless you have a specific reason to do so.

The configure program provides a button entitled

Edit "magick_config.h"

Clicking this button brings up magick_config.h in Windows notepad for optionally changing any preprocessor defines in GraphicsMagick's magick_config.h file. This file is copied to magick\magick_config.h. You may safely open magick\magick_config.h, modify it, and recompile without re-running the configure program. In fact, using notepad to edit the copied file may be preferable since it preserves the original magick_config.h file.

Key user tunables in magick_config.h include:

QuantumDepth (default 8)

Specify size of PixelPacket color Quantums (8, 16, or 32) A value of 8 uses half the memory than 16 and may run 30% faster, but provides 256 times less color resolution than a value of 16.

UseInstalledMagick (default undefined)

Define to build a GraphicsMagick which uses registry settings or embedded paths to locate installed components (coder modules and configuration files). The default is to look for all files in the same directory as