1.. -*- mode: rst -*- 2.. This text is in reStucturedText format, so it may look a bit odd. 3.. See http://docutils.sourceforge.net/rst.html for details. 4 5=============================== 6Magick++ API for GraphicsMagick 7=============================== 8 9.. _GraphicsMagick : ../index.html 10.. _ChangeLog : ChangeLog.html 11.. _`Standard Template Library` : http://www.sgi.com/tech/stl/ 12.. _deque : http://www.sgi.com/tech/stl/Deque.html 13.. _vector : http://www.sgi.com/tech/stl/Vector.html 14.. _list : http://www.sgi.com/tech/stl/List.html 15.. _map : http://www.sgi.com/tech/stl/Map.html 16.. _ftp : ../download.html 17.. _Mercurial: ../Hg.html 18.. _PerlMagick : ../perl.html 19.. _`GraphicsMagick Bug Tracker` : http://sourceforge.net/projects/graphicsmagick/ 20.. _`Bob Friesenhahn` : mailto:bfriesen@simple.dallas.tx.us 21 22.. _Blob : Blob.html 23.. _CoderInfo : CoderInfo.html 24.. _Color : Color.html 25.. _Drawable : Drawable.html 26.. _Exception : Exception.html 27.. _Geometry : Geometry.html 28.. _Image : Image.html 29.. _Montage : Montage.html 30.. _Pixels : Pixels.html 31.. _STL : STL.html 32.. _TypeMetric : TypeMetric.html 33.. _`Image::fontTypeMetrics` : Image.html#fonttypemetrics 34.. _`algorithms and function objects` : STL.html 35.. _`coderInfoList` : STL.html#coderInfoList 36 37.. contents:: 38 39Introduction 40------------ 41 42*Magick++* is the object-oriented C++ API to the GraphicsMagick_ 43image-processing library, the most comprehensive open-source image 44processing package available. Read the ChangeLog_ for *Magick++*. 45 46*Magick++* supports an object model which is inspired by PerlMagick_. 47Images support implicit reference counting so that copy constructors and 48assignment incur almost no cost. The cost of actually copying an image 49(if necessary) is done just before modification and this copy is managed 50automatically by *Magick++*. De-referenced copies are automatically 51deleted. The image objects support value (rather than pointer) semantics 52so it is trivial to support multiple generations of an image in memory at 53one time. 54 55*Magick++* provides integrated support for the `Standard Template 56Library`_ (`STL`) which is part of the standard C++ language so that 57the powerful containers available (e.g. deque_, vector_, list_, and 58map_) can be used to write programs similar to those possible with 59PERL & PerlMagick_. STL-compatible template versions of 60GraphicsMagick's list-style operations are provided so that operations 61may be performed on multiple images stored in STL containers. 62 63API 64--- 65 66*Magick++* provides a simple C++ API to the GraphicsMagick image 67processing library which supports reading and writing a huge number of 68image formats as well as supporting a broad spectrum of traditional image 69processing operations. The GraphicsMagick C API is complex and the data 70structures are not well documented. *Magick++* provides access to most of 71the features available from the C API but in a simple object-oriented and 72well-documented framework. 73 74*Magick++* is intended to support commercial-grade application 75development. In order to avoid possible conflicts with the user's 76application, all symbols contained in *Magick++* (included by the header 77<Magick++.h>) are scoped to the namespace Magick. Symbols from the 78GraphicsMagick C library are imported under the MagickLib namespace to 79avoid possible conflicts and GraphicsMagick macros are only included 80within the *Magick++* implementation so they won't impact the user's 81application. 82 83The InitializeMagick() function *MUST* be invoked before constructing 84any Magick++ objects. This used to be optional, but now it is 85absolutely required. This function initalizes semaphores and 86configuration information necessary for the software to work 87correctly. Failing to invoke InitializeMagick() is likely to lead to 88a program crash or thrown assertion. If the program resides in the 89same directory as the GraphicsMagick files, then argv[0] may be passed 90as an argument so that GraphicsMagick knows where its files reside, 91otherwise NULL may be passed and GraphicsMagick will try to use other 92means (if necessary). 93 94The core class in *Magick++* is the `Image`_ class. The `Image`_ class 95provides methods to manipulate a single image frame (e.g. a JPEG image). 96Standard Template Library (`STL`_) compatible algorithms and function 97objects are provided in order to manipulate multiple image frames or to 98read and write file formats which support multiple image frames (e.g. GIF 99animations, MPEG animations, and Postscript files). 100 101The `Image`_ class supports reference-counted memory management which 102supports the semantics of an intrinsic variable type (e.g. 'int') with an 103extremely efficient operator = and copy constructor (only a pointer is 104assigned) while ensuring that the image data is replicated as required so 105that it the image may be modified without impacting earlier generations. 106Since the `Image`_ class manages heap memory internally, images are best 107allocated via C++ automatic (stack-based) memory allocation. This support 108allows most programs using *Magick++* to be written without using any 109pointers, simplifying the implementation and avoiding the risks of using 110pointers. When a program uses automatic memory allocation to allocate 111*Magick++* images, that aspect of the program becomes naturally 112exception-safe and thread-safe. 113 114The image class uses a number of supportive classes in order to specify 115arguments. Colors are specified via the `Color`_ class. Colors specified 116in X11-style string form are implicitly converted to the `Color`_ class. 117Geometry arguments (those specifying width, height, and/or x and y 118offset) are specified via the `Geometry`_ class. Similar to the `Color`_ 119class, geometries specified as an X11-style string are implicitly 120converted to the `Geometry`_ class. Two dimensional drawable objects are 121specified via the `Drawable`_ class. Drawable objects may be provided as 122a single object or as a list of objects to be rendered using the current 123image options. `Montage`_ options (a montage is a rendered grid of 124thumbnails in one image) are specified via the `Montage`_ class. 125 126Errors are reported using C++ exceptions derived from the `Exception`_ 127class, which is itself derived from the standard C++ exception class. 128Exceptions are reported synchronous with the operation and are caught by 129the first matching try block as the stack is unraveled. This allows a 130clean coding style in which multiple related *Magick++* commands may be 131executed with errors handled as a unit rather than line-by-line. Since 132the `Image`_ object provides reference-counted memory management, 133unreferenced images on the stack are automatically cleaned up, avoiding 134the potential for memory leaks. 135 136For ease of access, the documentation for the available user-level 137classes is available via the following table: 138 139 140.. table:: *Magick++* User-Level Classes 141 142 +-------------+----------------------------------------------------------+ 143 |`Blob`_ |Binary Large OBject container. | 144 +-------------+----------------------------------------------------------+ 145 |`CoderInfo`_ |Report information about supported image formats (use with| 146 | |`coderInfoList`_\(\)) | 147 +-------------+----------------------------------------------------------+ 148 |`Color`_ |Color specification. | 149 +-------------+----------------------------------------------------------+ 150 |`Drawable`_ |Drawable shape (for input to 'draw'). | 151 +-------------+----------------------------------------------------------+ 152 |`Exception`_ |C++ exception objects. | 153 +-------------+----------------------------------------------------------+ 154 |`Geometry`_ |Geometry specification. | 155 +-------------+----------------------------------------------------------+ 156 |`Image`_ |Image frame. This is the primary object in *Magick++*. | 157 +-------------+----------------------------------------------------------+ 158 |`Montage`_ |Montage options for montageImages(). | 159 +-------------+----------------------------------------------------------+ 160 |`Pixels`_ |Low-level access to image pixels. | 161 +-------------+----------------------------------------------------------+ 162 |`STL`_ |STL algorithms and function objects for operating on | 163 | |containers of image frames. | 164 +-------------+----------------------------------------------------------+ 165 |`TypeMetric`_|Container for font type metrics \(use with | 166 | |`Image::fontTypeMetrics`_). | 167 +-------------+----------------------------------------------------------+ 168 169Obtaining Magick++ 170------------------ 171 172*Magick++* is included as part of GraphicsMagick_ source releases and may 173be retrieved via `ftp`_ or `Mercurial`_. 174 175Installation 176------------ 177 178Installation is very easy since *Magick++* is part of GraphicsMagick_ and 179is built by default. Once GraphicsMagick_ is built, then *Magick++* is 180available for use. 181 182Usage 183----- 184 185A helper script named *GraphicsMagick++-config* is installed in the same 186directory as the GraphicsMagick *gm* program under Unix which assists 187with recalling compilation options required to compile and link programs 188which depend on *Magick++*. For example, the following command will 189compile and link the source file example.cpp to produce the executable 190example (notice that quotes are backward quotes):: 191 192 c++ -o example example.cpp `GraphicsMagick++-config --cppflags --cxxflags 193 --ldflags --libs` 194 195Windows users may get started by manually editing a project file for one 196of the *Magick++* demo programs. 197 198It is necessary to initialize the GraphicsMagick library prior to 199using the *Magick++* library. This initialization is performed by 200passing the path to the GraphicsMagick DLLs (assumed to be in the same 201directory as your program) to the InitializeMagick() function 202call. This is commonly performed by providing the path to your program 203(argv[0]) as shown in the following example:: 204 205 int main( int /*argc*/, char ** argv) 206 { 207 InitializeMagick(*argv); 208 209If you don't have the path to your executable, then pass NULL and 210usually the library will be found anyway. Besides helping to find the 211GraphicsMagick DLL/library and configuration files, InitializeMagick() 212initializes all of the semaphores and data necessary for a 213multi-threaded program to be completely thread safe. This step used 214to be optional, but it is now absolutely required. Failure to 215initialize GraphicsMagick will result in an application crash. 216 217Reporting Bugs 218-------------- 219 220Please report any bugs via the `GraphicsMagick Bug Tracker`_. Questions 221regarding usage should be directed to `Bob Friesenhahn`_. 222 223.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN 224 225Copyright |copy| Bob Friesenhahn 1999 - 2020 226