fixed blended-decal rendering in textured mode
[xonotic/netradiant.git] / 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