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