[xonotic/netradiant.git] / contrib / bkgrnd2d / readme_bkgrnd2d-b0.25.txt
1 November 25 2003\r
2 bkgrnd2d v 0.25 beta for radiant 1.3.13\r
3 by SCDS_reyalP (email hellsownpuppy@yahoo.com)\r
4 \r
6 This is an beta release. It is provided with absolutely NO WARRANTY.\r
7 If it turns your data to mush and melts your CPU, don't blame me.\r
8 \r
9 Overview:\r
10 This little plugin allows you to display an image in the the gtkradiant 2d\r
11 windows. This is useful for layout sketches, maps made from\r
12 existing plans, building geometry based on photgraphs, viewing terrain\r
13 alphamaps in relation to your terrain, and so on.\r
14 \r
15 Installation:\r
16 extract the .dll and bitmaps into your gtkradiant/plugins directory, and\r
17 restart radiant. Be sure to use directory names, to ensure the bitmaps go\r
18 in your plugins/bitmaps directory.\r
19 \r
20 Uninstallation:\r
21 Close radiant, delete the bkgrnd2d.dll from the plugins directory, and \r
22 delete the bkgrnd2*.bmp files from the plugins/bitmaps directory.\r
23 \r
24 User Interface:\r
25 - The plugin adds 4 buttons to the radiant plugin toolbar. The first 3\r
26   toggle the display of a background image in the specified view. The fourth\r
27   brings up a configuration dialog. The configuration dialog can also be\r
28   opened from the plugins menu.\r
29 \r
30 - If an image has not been loaded, or it's display size and location have\r
31   not been set, pushing one of the toggle buttons will bring up the dialog\r
32   with the corresponding page selected.\r
33 \r
34 - The configuration dialog is non-modal, meaning that you can leave it open\r
35   while you work in radiant. If it gets lost behind another window, clicking\r
36   on the configuration button will bring it to the forground.\r
37 \r
38 Usage:\r
39 - bring up the configuration dialog.\r
40 \r
41 - Choose the "Browse..." button. This will prompt you for an image file.\r
42   The file *MUST* be inside your basegame directory (baseq3, main, etmain or\r
43   whatever your chosen game uses). The image must be in a format supported by\r
44   the game in use. For q3 based games this is truecolor .jpg, .tga and\r
45   sometimes .png. For q2 this is .wal\r
46 \r
47 - Use one of the following methods to set the size (in game units) that the\r
48   file is displayed. \r
49   1) select 1 or more brushes or entities and choose "from selection"\r
50      This will use the total dimensions off all selected brushes and entities\r
51          to size the image. \r
52   2) For the X/Y view only, choose 'Size to min/max keys' This will look in\r
53      the worldspawn entity for the keys mapcoordsmins and mapcoordsmaxs (also\r
54          used for ET tracemap generation and command map sizing) and use those\r
55          dimensions to size the image.\r
56 \r
57 - Use the toggle buttons to show or hide the loaded images. The buttons will\r
58   press or unpress whenever you click them, but an image will only be\r
59   displayed once you have successfully loaded a file and set its size/postion.\r
60 \r
61 - Set the opacity of the image using the slider in the configuration dialog.\r
62   \r
63 - If any of these commands do not produce the expected results, there may be\r
64   an information in the radiant console. Please include this when reporting\r
65   bugs.\r
66 \r
67 \r
68 Notes and limitations:\r
69 - This plugin is compiled for GtkRadiant 1.3.13. It may or may not work with\r
70   later versions. It will *NOT* work with version 1.3.12 and below. If you\r
71   build from source (see below) you can build it for other versions.\r
72 \r
73 - As mentioned above, the image *MUST* be inside your basegame directory, or \r
74   another directory in which radiant looks for game files.\r
75 \r
76 - To prevent the image from being distorted, you should size it to the\r
77   original images aspect ratio. mapcoordsmaxs/mapcoordsmins and command maps\r
78   should always be square.\r
79 \r
80 - If you want a specific pixel to world unit relationship, you must arrange\r
81   that yourself.\r
82 \r
83 - On load, the image is converted to a texture whose dimensions are powers\r
84   of 2. If the original image dimensions are not powers of 2, some detail will\r
85   be lost due to resampling. If it is too large to fit on a single texture,\r
86   resolution is reduced.\r
87 \r
88 - radiants gamma and mipmap options are applied to the image.\r
89 \r
90 - If the image has an alpha channel, it will be included in the blending\r
91   process. 0 is transparent, 255 is opaque. .tga images are recommended if\r
92   you want to have an alpha channel.\r
93 \r
94 - since the plugin will only use true color files, you cannot use a terrain\r
95   indexmap (aka alphamap) or heightmap directly. You can of course, save a\r
96   copy of your indexmap in a 32 bit format.\r
97 \r
98 - There is no unload command.\r
99 \r
100 - You put the plugin in a game specific plugin directory, rather than the\r
101   radiant plugin directory. \r
102 \r
103 - You cannot set the image size with sub-unit precision.\r
104 \r
105 - Only win32 binaries are included.  The source is available from:\r
106   http://www.cyberonic.net/~gdevault/rfm/mapstuff/bkgrnd2d-b0.25-src.zip\r
107   If you want to use it on another platform you will need a buildable gtkradiant\r
108   source tree to build it. For any non-windows platform you will also have to\r
109   figure out the compile options. I suggest ripping those off from some other\r
110   plugin.\r
111 \r
112 TODO:\r
113 - make file selection paterns match supported filetypes\r
114 - large images without downsampling\r
115 - bitmap and pcx support for indexmaps\r
116 - automatic size from indexmapped entities\r
117 - render under the grid instead of blending\r
118 - mac/*nix support\r
119 - remember/save/restore settings\r
120 - texture options independant of radiant prefs\r
121 - clean up icky code\r
122 \r
123 Changes from 0.1\r
124 - all 2d views supported\r
125 - new ui\r
126 - file selection patterns, default directory improved\r
127 \r
128 Changes from 0.2\r
129 - tooltips in dialog\r
130 - various code cleanup\r
131 \r