misc/mediasource/netradiant-src/plugins/md3model/doc/md3-design.txt

   1 map objects module
   2 ==================
   3
   4 Objective:
   5 ----------
   6
   7 #1 Turn the md3 code into a module. That is handle all aspects of map objects in
   8 a module. This involves:
   9 - the rendering of the model (sleep mode / shader reload are associated issues)
  10 - the manipulation in the editor (moving, rotating, (scaling?))
  11
  12 #2 Have an API generic enough to support other formats than md3. (md1 / md2 for
  13 multiple games support, any other formats).
  14
  15 What we have:
  16 -------------
  17
  18 What is the current implementation of md3 support? Were are the important
  19 features that we will need to work with?
  20
  21 "misc_model" is the required classname for any map object
  22
  23 entity_t::md3Class
  24 eclass_t  *md3Class;
  25 This holds the actual md3 object and the rendering information (tri soup,
  26 shader etc.)
  27 entity_t also has vRotation and vScale which are particular to the model
  28
  29 for selection of the brush (selection is preliminary step before any
  30 manipulation operation), we create a bounding box from the md3 information
  31 and use the entity's brush list as storage for it.
  32
  33 Requirements:
  34 -------------
  35
  36 Some technical requirements go on top of our objective given the existing
  37 implementation. The most important one is that the changes applied to the
  38 core must remain focused around the md3 functionality, and must also lay
  39 out the basics of some wider changes. We can identify some of those changes:
  40
  41 - introducing a more generalized way of selecting and manipulation things
  42 in the editor.
  43
  44 - introducing a more generic way of rendering objects in the editor.
  45
  46 More specifically, the details of rendering and manipulation:
  47
  48 transformation
  49   translate&rotate:
  50     A transformation increment is provided
  51     The object is transformed by a specified increment.
  52     Depending on the object type, the transformations may affect
  53     the local coordinate space transformation instead of the object.
  54     This local transformation is used in selection and rendering.
  55
  56 selection:
  57   ray:
  58     Radiant asks model for its world-relative axis-alignedbounding box.
  59     Radiant does intersection test with this bounding box.
  60     If test shows intersection, radiant gives model a ray_t, model tests
  61     for intersection with ray, model returns bool true if intersection
  62     A selection ray in world-space (origin+direction) is provided.
  63     The object must say whether or not it intersects with the ray.
  64       map objects have a special configuration to test on bounding box or trisoup
  65       this is set in preferences independently from the true/false selection tests
  66   area:
  67     radiant uses a bounding box for area selection. (bounding box can be
  68     infinite in some directions for the 'select tall' operations, in practice
  69     we just make them big enough).
  70
  71 rendering:
  72   geometry:
  73     Radiant tells the object what combination of 4 opengl states is currently active:
  74       none - draw as wireframe
  75       fill - draw as filled
  76       alpha blend - provide an opacity value
  77       texture_2d - provide a texture and texture coordinates
  78       lighting - provide normals, enable/disable smooth shading
  79     The object uses opengl to set up its geometry and to draw itself.
  80   material:
  81     The object provides a material name and is assigned a reference to
  82     a shader that matches the name.
  83     The shader contains the texture ID and the opacity value.
  84     The shader is a reference to an external script and must be refreshed
  85     on request.
  86
  87
  88 Proposed implementation:
  89 ========================
  90
  91 changes in shared interfaces (include/ directory):
  92 --------------------------------------------------
  93
  94 The following new interfaces will be added:
  95 most likely those interfaces will be implemented in the module
  96
  97 /*!
  98 something that can be selected
  99 */
 100 class ISelect
 101 {
 102   bool TestRay(ray_t) = 0
 103   bool TestBox(vec3_t vec_min, vec3_t vec_max) = 0;
 104 }
 105
 106 /*!
 107 something that can be selected for edition
 108 this must be synced with entity epairs
 109 (such as origin and angles keys)
 110 */
 111 class IEdit
 112 {
 113   void Translate(vec3_t v) = 0;
 114   void Rotate(vec3_t origin, vec3_t angles) = 0;
 115 }
 116
 117 for rendering, the existing IGL2DWindow and IGL3DWindow APIs
 118 we can define
 119 class IRender : public IGL2DWindow, public IGL3DWindow
 120 so that we have the Render2D and Render3D on the same class
 121
 122 entity_t will have to be modified, adding the following struct:
 123 typedef struct entity_interfaces_s
 124 {
 125   ISelect *pSelect
 126   IEdit *pEdit
 127   IRender *pRender
 128 }
 129 entity_interfaces_t;
 130
 131 When one of the pointers inside entity_t::entity_interfaces
 132 is != we will handle the entity differently that what we are
 133 doing by default. We will rely on these APIs for rendering,
 134 manipulation etc.
 135
 136 the AABB issue:
 137
 138
 139 changes in the core:
 140 --------------------
 141
 142 In all cases where the entity_t has to be drawn, tested for selection,
 143 manipulated (translation and rotation), add new code to go through the APIs.
 144
 145
 146 md3 module:
 147 -----------
 148
 149 static function table API
 150
 151 - registering of "model" module
 152 need some minors? "md3" etc.
 153
 154 - BuildEntity(entity_t)
 155 if an entity involved with models is found, core will call this
 156 entity_t::entity_interfaces will be filled with the relevant classes
 157
 158 (NOTE:L we don't have a need right now to manipulate a model that
 159 would not be part of an entity. so let's not try to guess what it
 160 would be like)
 161
 162 CModel
 163 stores the trisoup, local AABBs, references to shaders
 164 (CModel potentially needs a CModelManager to handle
 165 model loads and cached models queries)
 166
 167 CModelEntity implements IRender ISelect IEdit
 168 stores an entity_t*
 169 implements the interfaces pointed to in the entity_t
 170 is reference counted obviously
 171 stores a CModel*, calls up to it with entity information for rendering
 172