meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
vertexpacker [2021/03/15 11:25] – croftvertexpacker [2023/04/03 18:40] (current) – steph.jorgensen
Line 1: Line 1:
-====== Vertex Packing ======+====== Vertex packing ======
  
 In export formats that support it (currently only STSDK, used with the SpeedTree SDK), vertex packing lets you have complete control over the data stored in each vertex in the exported file, which allows the file data to be loaded directly into render buffers at runtime.  In export formats that support it (currently only STSDK, used with the SpeedTree SDK), vertex packing lets you have complete control over the data stored in each vertex in the exported file, which allows the file data to be loaded directly into render buffers at runtime. 
Line 23: Line 23:
     >     >
         <Attribute         <Attribute
-            Type=[type of variable used for this attribute: byte, byte, short, short, int, uint, half, float, or double]+            Type=[type of variable used for this attribute: byte, ubyte, short, ushort, int, uint, half, float, or double]
             Count=[integer for how many elements in this attribute, 1-4]             Count=[integer for how many elements in this attribute, 1-4]
             Normalize=[doesn't affect the packing, but does tell the runtime to normalize this attribute,              Normalize=[doesn't affect the packing, but does tell the runtime to normalize this attribute, 
Line 42: Line 42:
 <?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
 <SpeedTreeVertexPacker <SpeedTreeVertexPacker
- Program="Standard.lua" +      Program="Standard.lua" 
- Force32bitIndices="false" +      Force32bitIndices="false" 
- > +    > 
- <Stream Name="Main"> +    <Stream Name="Main"> 
- <Attribute Type="half" Count="4" Description="position(3) / texcoord_u(1)" /> +        <Attribute Type="half" Count="4"  
- <Attribute Type="half" Count="4" Description="lod_position(3) / texcoord_v(1)" /> +            Description="position(3)/texcoord_u(1)"/> 
- <Attribute Type="ubyte" Count="4" Normalize="false" Description="normal(1) / binormal(1) / tangent(1) / wind_branch_dir(1)" /> +        <Attribute Type="half" Count="4"  
- <Attribute Type="ubyte" Count="4" Normalize="true" Description="wind_weight(1) / wind_ripple(1) / wind_branch_offset(1) / ao_blend_and_2sided_packed(1)" /> +            Description="lod_position(3)/texcoord_v(1)"/> 
- </Stream>+        <Attribute Type="ubyte" Count="4" Normalize="false"  
 +            Description="normal(1)/binormal(1)/tangent(1)/wind_branch_dir(1)"/> 
 +        <Attribute Type="ubyte" Count="4" Normalize="true"  
 +            Description="wind_weight(1)/wind_ripple(1)/wind_branch_offset(1)/ao_blend_and_2sided_packed(1)"/> 
 +    </Stream>
 </SpeedTreeVertexPacker> </SpeedTreeVertexPacker>
 </code> </code>
  
- +===== Packing script =====
-===== Packing Script =====+
  
 During vertex packing, the packing script specified in the description XML file is run for each vertex. This script is written in Lua. While this documentation cannot cover every aspect of the Lua language, you can find additional info at [[http://www.lua.org/|www.lua.org]] and [[https://www.tutorialspoint.com/lua/index.htm|Lua Tutorials]]. During vertex packing, the packing script specified in the description XML file is run for each vertex. This script is written in Lua. While this documentation cannot cover every aspect of the Lua language, you can find additional info at [[http://www.lua.org/|www.lua.org]] and [[https://www.tutorialspoint.com/lua/index.htm|Lua Tutorials]].
Line 83: Line 86:
 |  in_tree_extents|(6 float array) - Tree extents: min xyz, max xyz| |  in_tree_extents|(6 float array) - Tree extents: min xyz, max xyz|
  
-The functions available to call in the script are as follows.+Besides built-in Lua calls, the functions available to call in the script are as follows.
  
 ^ Function^Parameters ^Description ^ ^ Function^Parameters ^Description ^
 |  set_attribute|<attribute index>, <component/swizzle index>, <double/float value> | save data to the vertex attributes | |  set_attribute|<attribute index>, <component/swizzle index>, <double/float value> | save data to the vertex attributes |
 |  set_attribute_integer|<attribute index>, <component/swizzle index>, <integer value> | save integer data to the vertex attributes | |  set_attribute_integer|<attribute index>, <component/swizzle index>, <integer value> | save integer data to the vertex attributes |
-|  set_batch_type| | +|  set_batch_type|<integer> |Set the batch type for this vertex. See [[#batching_control|batching control]] | 
-|  set_batch_priority| |+|  set_batch_priority|<float> |Set the batch priority for this vertex. See [[#batching_control|batching control]] |
 |  kill| |Completely remove this vertex (and the polygon with which it is associated) from the final mesh.| |  kill| |Completely remove this vertex (and the polygon with which it is associated) from the final mesh.|
 |  print|<string> |output information to the SpeedTree Modeler Console. This is usually used for debugging, but since it is run for every vertex, be careful printing too much. | |  print|<string> |output information to the SpeedTree Modeler Console. This is usually used for debugging, but since it is run for every vertex, be careful printing too much. |
  
-== Saving Vertex Data ==+=== Saving vertex data ===
  
-To place any of this data into the final vertex attributes in the export file, you use the set_attribute function or the set_attribute_integer function (when strict adherence to integers is wanted).+To place any of the input vertex data into the final vertex attributes in the export file, you use the set_attribute function or the set_attribute_integer function (when strict adherence to integers is wanted).
  
-The value you pass to these functions will get converted to the final data type as close as possible. In this fashion, you don't have to worry about packing a float into a half float or even a byte, as the set_attribute* functions will attempt to do this for you.+The value you pass to these functions will get converted to the final data type as close as possible. In this fashion, you don't have to worry about packing a float into a half float or even a byte, as the set_attribute functions will attempt to do this for you. 
 + 
 + 
 +=== Batching control === 
 + 
 +The geometry in the tree is as batched as much as possible, just like in other file formats. Without any further input, the tree will be batched into as few draw calls as it can, depending on the number of separate materials occur after atlassing.  
 + 
 +However, from the vertex packing script, you have some control over this. The set_batch_type function can pull geometry out into a separate draw call. You might want to pull anything with a blend/alpha value other than 1.0 out into a separate draw call to avoid rendering the whole tree with alpha blending on, for example. 
 + 
 +To do this, you can set any integer you wish to set_batch_type. What integer that is is up to you, and the default it 0. Any unique integer passed will cause a new draw call filled with all of the geometry set to that integer. The batch type value is available in the file and through the SpeedTree SDK to do with as you wish at run-time. You can encode all sorts of things into the batch type, and cause different rendering states or shaders to be used at runtime on that piece of geometry.  
 + 
 +Polygons are made up of multiple vertices, and they may have different values for the code used in set_batch_type. You may want to make sure that a certain vertex value takes priority over the other vertices in that polygon. To do this, use set_batch_priority. With the previous example of pulling out polygons needing alpha blending, you would set the priority to 1 if blend/alpha is less than 1.0 and 0 otherwise. This ensures that any polygon needing to be put into the batch type of 1 will get that value. 
 + 
 +<code> 
 +-- LUA BATCHING EXAMPLES 
 + 
 +-- batch by geometry type 
 +set_batch_type(in_geometry_type) 
 + 
 +-- batch by two-sided or not 
 +if in_two_sided then 
 +    set_batch_type(1) 
 +else 
 +    set_batch_type(0) 
 +end 
 + 
 +-- batch by needing blending 
 +if (in_vertex_alpha < 1.0) then 
 +    set_batch_type(1) 
 +    set_batch_priority(1.0) 
 +else 
 +    set_batch_type(0) 
 +    set_batch_priority(0.0) 
 +end 
 + 
 +-- batch by geometry type AND two-sided 
 +if in_two_sided then 
 +    set_batch_type(in_geometry_type + 5) 
 +else 
 +    set_batch_type(in_geometry_type) 
 +end 
 + 
 +</code>
  
  
-== Batching Control ==