addons-contrib: more view_layer syntax updates
[blender-addons-contrib.git] / io_directx_bel / README
1 a DirectX importer addon for Blender 2.6\r
2 \r
3 first goals :\r
4 \r
5 . to import anything from an .x file.\r
6   obviously verts, faces but uv, armatures, weights, normals...\r
7 . import .x in binary format too\r
8 \r
9 horizon :\r
10 . export to .x or mod/co-maintain the existing x exporter.\r
11 . this project is also a prototype for a 'Blender Exchange Layer' project.\r
12   BEL would be a common layer logically located between an importer/exporter\r
13   addon and the blender data format, that would allow :\r
14     . to provide a common set of methods to retrieve/inject objects in Blender\r
15     . to provide a common set of transformation and selection tools between an\r
16       import/export script and Blender datas (rotate, rescale, filters...)\r
17     . to provide a common set of parsing helpers for new io addons\r
18 \r
19 PLY won't be used unfortunately (it's way too slow as far as I tested)\r
20 \r
21 \r
22 TO TEST THE SCRIPT :\r
23   . copy the 'io_directx_bel' in /scripts/addons or addons_contrib\r
24   . start blender\r
25   . enable then addon in  user prefs > addons\r
26   . run the script with file > import > directX\r
27  \r
28 25/01/12 0.18\r
29   . code rewrite according to api bmesh changes (me.polygon and uv layers essentially)\r
30   . implemented foreachset() call for uv import (faster)\r
31   \r
32 25/01/12 0.17\r
33   . faster, 60% faster in some case : various loops improvements, infile templates parsing disabled by default\r
34     saw another bottleneck about data chunks as string but will wait for binary support for better point of view.\r
35   . interface cosmetics\r
36     \r
37 23/01/12 rc 0.16\r
38 . committed to svn (and littleneo git as usual)\r
39 . corrected a bug about referenced token parenting\r
40 . corrected a bug about non parented meshes\r
41 . armatures/empties importation enabled by default\r
42 . last run importer options are saved in a 'last_run' preset,\r
43   so it can be replayed or saved under another name once a\r
44   particular .x profile has been defined\r
45 . tagged script for 2.6.1\r
46 \r
47 12/01/12 rc 0.15 :)\r
48 . name conversion changed from 5 to 4 digits\r
49 . matname, imagename and texturename fixes :\r
50 . a path test is made at image import time with any existing data images, \r
51   so a same file cant be loaded twice wathever the naming method, / or \, rel or abs etc \r
52   (bel.material.new() and after line 835)\r
53 . image and texture names should be ok now (tested with : incrediblylongname.x)\r
54 . materials are replaced accordingly in existing objs when using the 'replace' naming method\r
55 . fyi, the Dx exporter has the following inconveniences :\r
56     . split linked faces into individual faces\r
57     . inversed uvmapping (y axis) ?\r
58     -> see testfiles/blender_x_export/incrediblylongname.x\r
59    \r
60 29 and 31/12/11\r
61 . Cosmetics, code cleaning and optimizations\r
62 . bpy.ops.object.select_name methods replaced with\r
63     ob.select = True\r
64     bpy.context.scene.objects.active = ob\r
65 . corrected a big bug about tokens info appending in dXtree()\r
66 . new bpyname() method in bel module. removed bel.common\r
67 \r
68 26/12/11\r
69 . armature import and bone max. length option\r
70 \r
71 23/11/11\r
72 . contrib candidate :)\r
73 . solved some naming cases, added bel methods.\r
74 . added experimental option about parenting (no armature yet just empties, when needed)\r
75 . a bit faster\r
76 . added some test files (empty parenting, armature etc)\r
77 \r
78 22/11/11\r
79 campbell feedback (cont):\r
80 . added naming methods as options (default is blender name inc. if name exists)\r
81   me and ob remove() should be ok with special cases (empties, mesh with multi-users)\r
82 . improved ui\r
83 \r
84 \r
85 21/11/11\r
86 campbell feedback :\r
87 . converted immutables to tuples : templates_x.py and some other vars.\r
88   http://stackoverflow.com/questions/3340539/why-tuple-is-faster-than-list\r
89 . dprint() (console debug) removed, replaced by a inloop tests (a bit faster)\r
90   I'd like to keep it for now for easier debug (eg user feedbacks with 'processing' option)\r
91   \r
92 19/11/11\r
93 . object parenting support. parsing the x tree from roots using import_dxtree()\r
94   actually faster than before\r
95   \r
96 16/11/11\r
97 . weight group import\r
98 . improved ui a bit and console logs\r
99 . x matrices to blender ones conversion\r
100 \r
101 14/11/11\r
102 . global matrix options\r
103 . added messy code about binary (not working)\r
104 \r
105 11/11/11\r
106 . import materials and textures (basics) : uv and image mapped (multitex mode)\r
107   and material created with tex slot if any. alpha should be ok.. ?\r
108 . added a smooth options\r
109 . better tolerance with faulty .x (upper/lower case of template names)\r
110 . token names length from x to blender conversion should be ok also (long name cases)\r
111 . corrected a parser pointer error after one array parsing case.\r
112 . added more templates (for mat and tex support)\r
113 . removed texture files from repo in testfile (tex does not match meshes )\r
114   added some other x files for further tests in binary and compressed format\r
115   ( http://assimp.svn.sourceforge.net/viewvc/assimp/trunk/test/models/X/ )\r
116   \r
117 08/11/11\r
118 . turned into an addon (fork from obj import so unused functions atm)\r
119   enable it in addon, then file > import > directx\r
120 . splitted directx parser (io_directx_bel folder) and bel draft \r
121   the bel folder is intended to be located in /scripts/modules (shared components)\r
122   but it's ok in scripts/addons too (tbd)\r
123   bel folder (will) includes anything related to blender data helper (read/write)\r
124 . corrected duplicated quotes for x string type\r
125 \r
126 07/11/11\r
127 . uv import\r
128 . generic directx token parser. templates items are used to read datas of any token type\r
129   a bit slower but cool since it should support non strict standard directx files\r
130   virtually it can retrieve everything from now supposing the template is know\r
131   by default or given in the file. calls are now like :\r
132                 nbslots, mats = readToken('MeshMaterialList001') or\r
133                 uv = readToken('uv001') or\r
134                 nVerts, verts, nFaces, faces = readToken('Hydralisk_backbone1') etc\r
135 . removed the specific mesh parser the 'rigid' file is the last before mutation to\r
136   generic parser. a bit faster but harder to make evolve or adapt. keep it as a faster\r
137   strict 'branch'\r
138 . added some default templates\r
139   goals / wip :\r
140   . to compare template declaration in file and default one.\r
141     so either use the default one (strict) or the .x one (could differ)\r
142   . use by the generic data parser to avoid a parser for each kind of token\r
143 . cleaner code (grouping methods, function names, docs etc) \r
144   functions separated from calls\r
145   renamed token dict as tokens etc\r
146 . added tweaks at the beginning of the file :\r
147         chunksize = 1024     # size of file streams red in a row\r
148         quickmode = False    # this to only find meshes (no parenting, no other tokens than Mesh ones)\r
149         showtree = False     # display the entire token tree in the console\r
150         showtemplate = True  # display template datas found in file\r
151 . added a patch for malformed datas of vertices (meshFaces) :\r
152         # patch for malformed datas not completely clear yet ( I guess\r
153         # there's bunch of us when looking at meshface syntax in .x files) :\r
154         # when array members are like 3;v0,v1,v2;,\r
155         # and not like 3;v0;v1;v2;, depending on template declarations.\r
156         # http://paulbourke.net/dataformats/directx/#xfilefrm_Use_of_commas\r
157 . the script now generates linked faces (was not my fault !)\r
158   > it seems Dx always separate each face :\r
159   so it defines (vert * linked faces) verts for one needed vert\r
160   the readvertices loop now remove duplicates at source\r
161   it uses a verts lookup list to redirect vert id defined in faces\r
162 \r
163 06/11/11\r
164 . vertices and faces imported from each test files\r
165 . added some info to test yourself in README \r
166 . switched to binary for .x as text to retrieve eol (pointer bugs). should be ok whatever it's win, mac or unix text format,\r
167   also works with mixed eol.\r
168   it seems python 3.1 can't return a 'line' when data.realine() when read mode is 'rb' (U default and universal ? really ? ;) ) \r
169   when file has mac eol (\r)\r
170   -> read(1024) in binary, decode, and replace any \r with \n. yes, it doubles lines for windows and lines value is wrong for now\r
171   -> but the used pointer value is always ok now whatever the file format and still way faster than a data.tell()\r
172   see CRCF folder to compare output wispwind.x by format.\r
173 . files are still splitted into chunks (1024 B) and readable as lines\r
174 . references : added 'user' fields when token is used. users store a reference with their childs but with a '*' tag at chr0.\r
175   the tree reflects the changes\r
176 . now read anything and add it to the 'tree'. this includes unknow tokens.\r
177 . references are recognized. by reference I mean fields like { cube0 } rather than an inline frame cube0 {\r
178   declaration.\r
179   I don't know if one item can be referenced several time or referenced before declaration\r
180   should be.. waiting for a case. for now only one 'parent' token, messages will show up\r
181   multi references to one token if cases arise. \r
182 . more permissive syntax : 'frame spam{', 'frame     spam   egg{', 'frame spam egg  {'..\r
183 . comments are recognized (inlines ones not done yet, since still no useful data red :) )\r
184 . header is red\r
185 . found other .x test files here :\r
186   http://www.xbdev.net/3dformats/x/xfileformat.php\r
187   created from 3ds max\r
188 . added .x files in repo. line 70 and following to switch.\r
189 . some token comes with no names, add a noname<00000> to them\r
190 . console gives line number (more useful than char position I guess)\r
191 \r
192 \r
193 05/11/11        day 0 :\r
194 \r
195 . made some disapointing test with ply (from a speed point of view, else it looks really cool)\r
196 . made my own parser\r
197 . nothing imported for now, it's more about self-eduction to .x and concept\r
198 . but it reads the .x structure and can gather some info\r
199 \r
200 resource gathered :\r
201 \r
202 http://paulbourke.net/dataformats/directx/\r
203 http://www.informikon.com/various/the-simplest-skeletal-animation-possible.html\r
204 http://msdn.microsoft.com/en-us/library/windows/desktop/bb173011%28v=VS.85%29.aspx\r
205 http://www.toymaker.info/Games/index.html\r
206 \r
207 \r
208 \r
209 step 1 : read main structure :\r
210 \r
211     read main token names (any 'template', any 'frame', any 'mesh')\r
212     stores names in a token directory :\r
213         token['template'] for templates :\r
214             token['template'][templatename]\r
215             token['template'][templatename]['pointer']          (int) chr position in .x file (tell() like*)\r
216             token['template'][templatename]['line']             (int) line number in .x file\r
217         token['frame'] for frame and mesh type :\r
218             token['template'][frame or mesh name]\r
219             token['template'][frame or mesh name]['pointer']    (int) chr position in .x file (tell() like*)\r
220             token['template'][frame or mesh name]['line']       (int) line number in .x file\r
221             token['template'][frame or mesh name]['type']       (str) 'ob/bone' or 'mesh'\r
222             token['template'][frame or mesh name]['parent']     (str) frame parent of current item\r
223             token['template'][frame or mesh name]['childs']     (str list) list of child frame or mesh names\r
224             token['template'][frame or mesh name]['matrix']     (int) for now chr position of FrameTransformMatrix\r
225 \r
226 at the end of step 1 the script prints a tree of these datas\r
227 \r
228 step 2 : read template definitions :\r
229 \r
230     for each template in dict, populate definitions in it.\r
231     it creates new fields in each token['template'][templatename]\r
232     according to values found in .x :\r
233         token['template'][templatename]['uuid']                 (str) <universally unique identifier>\r
234         token['template'][templatename]['members']['name']      (str) member name\r
235         token['template'][templatename]['members']['type']      (str) DWORD,FLOAT etc keywords or template name\r
236         token['template'][templatename]['restriction']          (str) 'open' , 'closed' , or the specidied (restricted) value\r
237 \r
238 that's all for now.\r
239 \r
240 idea would be to allow 2 steps importation and random access to file :\r
241 \r
242     . first the file is quickly parsed. we only retrieve main info, nothing about verts, faces etc\r
243     info like number of mats, textures, objects/mesh/bone trees\r
244     for now : 150000 lines in 5 secs for step 1\r
245     . then user select what to import\r
246     . then the script retrieve selected datas according to selection, using the 'pointer' value\r
247       to seek() to the needed data, then grab/parse/translate in something usable.\r
248     . template are used at this point to know how to parse a specific part (adaptive parser)\r
249           \r
250     so far this looks fast.\r
251         \r
252 tested on windows. can be important because of eol and the code I wrote to compute pointer value.\r
253 (data.tell() is slow)\r
254 only one .x file tested, header is : xof 0303txt 0032 (windows \r\n eol)\r
255 \r
256 don't know a lot about .x format :\r
257 \r
258 uuid : \r
259   are the member/restriction always the same for a same uuid/template ?\r
260   template name can vary for a same uuid ?\r
261 syntax :\r
262   blank lines IN a stream of a {} section, after ; ?\r
263   comments // and # IN a stream of data ?\r
264   '{' and '<something>' and '}' on the same line or '{' '}' are always unique ?\r
265   \r
266