setup/PluginSDK/README.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="GENERATOR" content="Mozilla/4.73 [en] (Win98; U) [Netscape]">
   6    <title>Q3Radiant plugin SDK
   7 </title>
   8 </head>
   9 <body>
  10
  11 <center><b><font size=+2>GtkRadiant plugin SDK</font></b></center>
  12 <center><b><font size=+2>http://www.gtkradiant.com</font></b></center>
  13
  14 <p><br>
  15 <div align=right><b><font size=+2>Version: <font color="#FF0000">GtkRadiant
  16 1.1-TA-beta</font></font></b>
  17 <br><b><font size=+2><font color="#000000">Last updated: </font><font color="#FF0000">01/14/2001</font></font></b></div>
  18
  19 <p><br>
  20 <hr WIDTH="100%"><font size=+2>What do I have?</font>
  21
  22 <br><font size=+1><tt>GtkRadiant/include/</tt>: Radiant plugin API
  23 headers</font>
  24
  25 <br><font size=+1><tt>GtkRadiant/plugins/sample/</tt>: an empty plugin nutshell,
  26 handy to start a new one (NOTE: a cygwin makefile for Sample is also
  27 provided)</font>
  28
  29 <br><font size=+1><tt>GtkRadiant/plugins/textool/</tt>: TexTool plugin
  30 source code</font>
  31
  32 <br><font size=+1><tt>src/</tt>: Gtk headers and libraries for win32</font>
  33
  34 <p> <font size=+2>A Word about Gtk:</font>
  35
  36 <br><font size=+1>GtkRadiant is using the <a href="http://www.gtk.org"
  37 target="_new">Gtk toolkit</a> for all the user interface. There's a specific
  38 page for the <a href="http://user.sgic.fi/~tml/gimp/win32/" target="_new">Gtk on
  39 win32</a>. If you are going to write a plugin for GtkRadiant, we recommend you
  40 use Gtk, but it's not a required feature. You can write plugins using the native
  41 windows API or even VB. Don't hesitate to ask for help on the <a
  42 href="http://www.egroups.com/register?referer=/subscribe/radiant-plugins"
  43 target="_new">plugin mailing list</a> or to drop by on irc.telefragged.com
  44 #qeradiant</font></p>
  45
  46 <p><font size=+2>Plugin basics:</font>
  47 <br><font size=+2>main features available to plugins:</font>
  48 <ul>
  49 <li>
  50 <font size=+1>Manipulate MAP data: read and write brushes, patches, epairs and entities</font></li>
  51
  52 <li>
  53 <font size=+1>Override the BSP menu to process your own building commands</font></li>
  54
  55 <li>
  56 <font size=+1>Read / Write project settings epairs</font></li>
  57
  58 <li>
  59 <font size=+1>Use OpenGL to draw in the 2D/3D view, or in your own plugin
  60 windows</font></li>
  61
  62 <li>
  63 <font size=+1>Use listeners to catch events in Radiant (like a change of
  64 texture or brush select / deselect)</font></li>
  65
  66 <li>
  67 <font size=+1>Use listeners to listen for window events (for mouse interaction
  68 in the 2D view)</font></li>
  69
  70 <li>
  71 <font size=+1>Create new plugin entities that show up in the Radiant window,
  72 which you can draw yourself and handle the user interaction</font></li>
  73
  74 <li>
  75 <font size=+1>Use the Radiant internal parser to hook your own MAP format
  76 changes for plugin entities</font></li>
  77
  78 <li>
  79 <font size=+1>Access polygon and texture information on the current selected
  80 face</font></li>
  81
  82 <li>
  83 <font size=+1>Override the texture / shader code to provide your own texture
  84 formats and shader system</font></li>
  85
  86 <li>
  87 <font size=+1>Add new surface properties, and change the MAP format accordingly</font></li>
  88 </ul>
  89 <font size=+2>overall structure of a plugin:</font>
  90 <br><font size=+1>A plugin is a DLL (dynamic loading library) that exposes
  91 some API to Radiant. Plugins must be put in the plugins/ directory, they
  92 get loaded at startup by Radiant. Any plugin has a few required entry points
  93 in order to get loaded correctly:</font>
  94 <ul>
  95 <li>
  96 <font size=+1><tt>QERPlug_Init</tt> is the first entry point called, used
  97 for initialization and sending back the plugin name that appears in the
  98 console</font></li>
  99
 100 <li>
 101 <font size=+1><tt>QERPlug_GetName</tt> returns the name of the plugin as
 102 it appears in the plugin menu</font></li>
 103
 104 <li>
 105 <font size=+1><tt>QERPlug_GetCommandList</tt> returns a list describing
 106 the items in the plugin submenu</font></li>
 107
 108 <li>
 109 <font size=+1><tt>QERPlug_GetFuncTable</tt> returns the address of the
 110 _QERFuncTable_1 of the plugin. After Radiant got the pointer to the function
 111 table it will fill it and the plugin is able to call into the editor.</font></li>
 112
 113 <li>
 114 <font size=+1><tt>QERPlug_Dispatch</tt> is called when the user hits a
 115 command in the plugin menu. The plugin is then free to process.</font></li>
 116 </ul>
 117 <font size=+2>the function table and interfaces:</font>
 118 <br><font size=+1>Instead of exporting entry points, Radiant fills in function
 119 pointer tables. The main and required function table is <tt>_QERFuncTable_1</tt>.
 120 Each plugin must have it and let Radiant fill it. Some additional or specialized
 121 functionalities can be accessed with other tables like <tt>_QERQglTable</tt>
 122 for GL stuff. These have to be requested to Radiant using <tt>_QERFuncTable_1::m_pfnRequestInterface</tt>
 123 (see <tt>TexTool</tt> for an example). Each additional function table has
 124 a "globally unique identifier" (<tt>QERQglTable_GUID</tt> for GL stuff)
 125 that's used to identify the interface across plugins.</font>
 126 <p><font size=+1>NOTE: some function tables are used by Radiant and must
 127 be filled by the plugin (ie. they work in reverse compared to usual ones).
 128 In this case the plugin must export an additional entry point <tt>int WINAPI
 129 QERPlug_RequestInterface( REFGUID, LPVOID );</tt></font>
 130 <p><font size=+2>virtual classes:</font>
 131 <br><font size=+1>some stuff is better represented by an abstract C++ class.
 132 For those with COM knowledge, it's just a very lightweight COM way of doing
 133 things. These classes have very basic reference counting through <tt>IncRef()</tt>
 134 and <tt>DecRef()</tt> .. you are supposed to increment or decrement the
 135 reference count each time you store or release a pointer to these classes,
 136 otherwise they could get unexpectedly erased and you would be very very
 137 sorry. The <tt>IListener</tt> class in <tt>IMessaging.h</tt> can be implemented
 138 by the plugin and handed over to Radiant to listen for events. See <tt>TexTool</tt>
 139 for examples.</font>
 140 <br>&nbsp;
 141
 142 <p><font size=+2>More stuff:</font>
 143
 144 <br><font size=+1>If you need more information or if you want new features for
 145 plugins, see the source code for <tt>TexTool</tt> and <tt>Curry</tt>.
 146 <tt>TexTool</tt> source comes with the plugin SDK, and <tt>Curry</tt> source is
 147 available <a href="http://curry.sourceforge.net">from their web site</a>. You
 148 can <a
 149 href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=curry">browse it
 150 online</a> from <a href="http://sourceforge.net/project/?group_id=1263">the
 151 project page</a>. <a
 152 href="http://sourceforge.net/project/?group_id=5326">PrtView</a> has neat code
 153 samples on how to draw in the 2D views or camera window. These two plugins are
 154 under GPL licensing. The dedicated place to talk about plugin coding is the <a
 155 href="http://www.egroups.com/group/radiant-plugins">plugins-coding mailing
 156 list</a> ... see you there. You may also get an updated list of the plugins for
 157 Radiant <a href="http://plugins.qeradiant.com">on our dedicated web
 158 site</a>.<br>
 159
 160 Update: you can also have a look to the <a
 161 href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=pk3man "
 162 target="_new">pk3man source</a>.</font>
 163
 164 <p><font size=+2>Conclusion:</font>
 165 <br><font size=+1>this document is intended as a quickstart for potential
 166 plugin writers. I hope it meets it's objective. It's not a complete and
 167 systematic documentation, I doubt there will be one ever unless someone
 168 decides to do it. Feel free to send me contributions to this document.
 169 <a href="mailto:timo@qeradiant.com">Send feedback to me</a>.</font>
 170 </body>
 171 </html>