Date: 2009-10-04 17:03:08 +0000 (Sun, 04 Oct 2009)
Completely update/modernize this file.
--- trunk/drivers/README.drivers 2009-10-01 23:50:16 UTC (rev 10511)
+++ trunk/drivers/README.drivers 2009-10-04 17:03:08 UTC (rev 10512)
@@ -7,175 +7,66 @@
"Output Devices" and "Driver Functions" in Chapter 3] that you should look
-The following PLplot system files must be modified to add a new driver to
+The following are some short notes on what PLplot source tree files need
+to be added or modified in order to add a device (which we'll call <device>) to
+a device driver (which we'll call <driver>).
+The following PLplot source-tree files are affected:
-The following are some short notes on what you need to add to these files
-to add a new driver (which we'll call foo) to PLplot.
+1. Add a line to plplot/drivers/<driver>.rc.in consisting of the following
-1. Add the following 2 lines to config.h.cmake:
-/* Define if foo driver is present */
+<device>:<description string>:<interactive?>:<driver>:<device number>:<device>
-Note that drivers are listed in alphabetical order.
+This should be the exact duplicate of the corresponding entry in the
+driver source code for plD_DEVICE_INFO_<driver>.
-2. Add the following line to cmake/modules/drivers-init.cmake in set(DRIVERS_DEVICE_LIST...
+2. Add the following line to plplot_cmake/modules/drivers-init.cmake in
-This is also (mostly) in alphabetical order.
-3. Add the following line to include/drivers.h:
-void plD_dispatch_init_foo ( PLDispatchTable *pdt );
+where that file documents how the last two fields should be set depending
+on the characteristics of the device you are adding.
+3. Add the following line to plplot/include/drivers.h:
+PLDLLIMPEXP_DRIVER void plD_dispatch_init_<device> ( PLDispatchTable *pdt );
4. Add the following line to include/plDevs.h.cmake
-5. Add the following 3 lines to include/plcore.h:
-#if defined(PLD_foo) && !defined(ENABLE_DYNDRIVERS)
+5. Add the following 3 lines to plplot/include/plcore.h:
+#if defined(PLD_<device>) && !defined(ENABLE_DYNDRIVERS)
6. For each _file_ device of the driver add the following line to
-test/plplot-test.sh.cmake. For completeness you may want to specify
-the interactive devices there as well but be sure to comment them out since
-the configured plplot-test.sh script does not work with interactive devices.
-If the driver requires additional additional files or external libraries for
-compiling and linking then you should add a file called foo.cmake to
-plplot/cmake/modules and add a call to this file in the file plplot/cmake/
-modules/drivers.cmake (include(foo)). The file foo.cmake should consist of
-cmake instructions for finding and the files and libraries and setting the
-appropriate environment variables (PLD_foo, foo_COMPILE_FLAGS and
+For completeness you may want to specify the interactive devices there as
+well but be sure to comment them out since the configured plplot-test.sh
+script does not work with interactive devices.
-The code for the driver itself should be in a file called foo.c or foo.cpp in
-the plplot/drivers directory.
+7. Add the following line to
+If the driver requires additional additional files or external libraries for
+compiling and linking then you should add a file called <driver>.cmake to
+plplot/cmake/modules and add a call to this file in the file
+plplot/cmake/modules/drivers.cmake (include(<driver>)). The file
+<driver>.cmake should consist of cmake instructions for finding and the
+files and libraries and setting the appropriate environment variables
+(PLD_<driver>, <driver>_COMPILE_FLAGS and <driver>_LINK_FLAGS).
-Deprecated Autotools Information
-The following is the list of PLplot system files that must be modified if
-you are creating a new PLplot driver:
-plplot/cf/*.ac (e.g., plplot/cf/gd.ac)
-plplot/drivers/*.c (e.g., plplot/drivers/gd.c)
-where plplot is the top-level directory for the plplot software tree that is
-created when you unpacked the tarball (or used cvs checkout).
-Some short notes follow on what is done for the individual files mentioned
-above. Basically, you should be okay if you just try to follow what is done
-for the gd.c driver, the associated png and jpeg devices, and any additional
-headers or libraries you might require for your driver. (libgd, libjpeg,
-libpng, and libz are required for the gd driver to work and are found on
-the user's system with the aid of the macros in the cf/gd.ac file.).
-* plplot/configure.ac with plplotcf/gd.ac as an example of what is required
-for the gd device driver (which could be used as a template for other new
-Note, configure.ac has the line
-that includes the gd.ac file. That latter file is used to find the system
-resources used by the gd device. If you look in that file you will see logic
-for finding and testing the required system headers and include libraries,
-enabling or disabling the jpeg and png devices associated with the gd
-driver, and ultimately forming GDINCCMD and GDLIBCMD which summarizes this
-information. For your new driver, follow this same paradigm, i.e. include
-command in configure.ac, and the corresponding cf/*.ac for your particular
-device driver. For more details see plplot/cf/README.
-* Some additional setup of the png and jpeg devices for the gd driver is
-done in plplot/cf/drivers-pre.ac with the line
-Add in a similar line for your own list of devices for your driver.
-* Some additional setup of devices is done in plplot/cf/drivers-post.ac.
-I have no idea why that is separated from plplot/cf/drivers-pre.ac, but
-there is nothing relevant to gd there, and probably not for your device driver
-The entries in this file for the png and jpeg devices associated with the gd
-These entries inform the configure script to store the actual configured
-(say) in the created file plplot/include/plDevs.h.
-In turn, the information in this header is used in drivers/gd.c to decide
-which of the associated devices to compile.
-This file tells automake and libtool how to build the various drivers, what
-libraries must be linked to them, etc., for the two cases of
---enable-dyndrivers (where the drivers are built as loadable modules [i.e.,
-plug-ins or DLL's]) and --disable-dyndrivers (where the drivers are built
-and stored in a libtool convenience library which eventually becomes part of
-libplplot). For the gd driver look for all references to gd. You will see
-references to GDINCCMD and GDLIBCMD that are set up with sysloc.in and
-This file contains prototype definitions that occur in drivers/*.c. For the
-gd driver, these prototypes are
-void plD_dispatch_init_jpeg ( PLDispatchTable *pdt );
-void plD_dispatch_init_png ( PLDispatchTable *pdt );
-The point of plD_dispatch_init_??? is to initialize the driver dispatch
-table with the data it needs to know. Look for void plD_dispatch_init_jpeg
-and void plD_dispatch_init_png in drivers/gd.c.
-This file contains a definition of the table static_device_initializers. In
-the jpeg and png case the relevant lines are
-#if defined(PLD_png) && !defined(ENABLE_DYNDRIVERS)
-#if defined(PLD_jpeg) && !defined(ENABLE_DYNDRIVERS)
-This is where the core of the driver software is defined. plplot/drivers/gd.c
-contains the software defining the gd driver with the associated png and jpeg
+The code for the driver itself should be in a file called <driver>.c or
+<driver>.cpp in the plplot/drivers directory.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.