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