/extra/game/models/collada/collada-docs.factor

 1! Copyright (C) 2010 Erik Charlebois
 2! See http://factorcode.org/license.txt for BSD license.
 3USING: help.markup help.crossref help.stylesheet help.topics help.syntax
 4definitions io prettyprint summary arrays math sequences vocabs strings
 5see xml.data hashtables assocs game.models.collada.private game.models
 6game.models.util ;
 7IN: game.models.collada
 8
 9ABOUT: "game.models.collada"
10
11ARTICLE: "game.models.collada" "Conversion of COLLADA assets"
12"The " { $vocab-link "game.models.collada" } " vocabulary implements words for converting COLLADA assets to data suitable for use with OpenGL. See the COLLADA documentation at " { $url "http://collada.org" } "." ;
13
14HELP: source
15{ $class-description "Tuple of a vertex attribute semantic, offset in triangle index buffer and float data for a single vertex attribute." } ;
16
17HELP: up-axis
18{ $description "Dynamically-scoped variable with the up axis of the tags being read." } ;
19
20HELP: unit-ratio
21{ $description "Scaling ratio for the coordinates of the tags being read." } ;
22
23HELP: string>numbers
24{ $values { "string" string } { "number-seq" sequence } }
25{ $description "Splits a string on whitespace and converts the elements to a number sequence." } ;
26
27HELP: x-up { $class-description "Right-handed 3D coordinate system where X is up." } ;
28HELP: y-up { $class-description "Right-handed 3D coordinate system where Y is up." } ;
29HELP: z-up { $class-description "Right-handed 3D coordinate system where Z is up." } ;
30
31HELP: >y-up-axis!
32{ $values { "seq" sequence } { "from-axis" rh-up } }
33{ $description "Destructively swizzles the first three elements of the input sequence to a right-handed 3D coordinate system where Y is up and returns the modified sequence." } ;
34
35HELP: source>sequence
36{ $values { "source-tag" tag } { "up-axis" rh-up } { "scale" number } { "sequence" sequence } }
37{ $description "Convert the " { $emphasis "float_array" } " in a " { $emphasis "source tag" } " to a sequence of number sequences according to the element stride. The values are scaled according to " { $emphasis "scale" } " and swizzled from " { $emphasis "up-axis" } " so that the Y coordinate points up." } ;
38
39HELP: source>pair
40{ $values { "source-tag" tag } { "pair" pair } }
41{ $description "Convert the source tag to an id and number sequence pair." } ;
42
43HELP: mesh>sources
44{ $values { "mesh-tag" tag } { "hashtable" pair } }
45{ $description "Convert the mesh tag's source elements to a hashtable from id to number sequence." } ;
46
47HELP: mesh>vertices
48{ $values { "mesh-tag" tag } { "pair" pair } }
49{ $description "Convert the mesh tag's vertices element to a pair for further lookup in " { $link collect-sources } ". " } ;
50
51HELP: collect-sources
52{ $values { "sources" hashtable } { "vertices" pair } { "inputs" tag sequence } { "seq" sequence } }
53{ $description "Look up the sources for these " { $emphasis "input" } " elements and return a sequence of " { $link source } " tuples." } ;
54
55HELP: group-indices
56{ $values { "index-stride" number } { "triangle-count" number } { "indices" sequence } { "grouped-indices" sequence } }
57{ $description "Groups the index sequence by triangle and then groups each triangle's indices by vertex." } ;
58
59HELP: triangles>numbers
60{ $values { "triangles-tag" tag } { "number-seq" sequence } }
61{ $description "Converts the triangle data in a triangles tag from string form to a sequence of numbers." } ;
62
63HELP: largest-offset+1
64{ $values { "source-seq" sequence } { "largest-offset+1" number } }
65{ $description "Finds the largest offset in the sequence of " { $link source } " tuples and adds 1, which is the index stride for " { $link group-indices } "." } ;
66
67HELP: pack-attributes
68{ $values { "source-indices" sequence } { "sources" sequence } { "attributes" sequence } }
69{ $description "Packs the attributes for a single vertex into a sequence from a set of source data streams." } ;
70
71HELP: soa>aos
72{ $values { "triangles-indices" sequence } { "sources" sequence } { "attribute-buffer" sequence } { "index-buffer" sequence } }
73{ $description "Swizzles the input sources from a structure of arrays form to an array of structures form and generates a new index buffer." } ;
74
75HELP: triangles>model
76{ $values { "sources" sequence } { "vertices" pair } { "triangles-tag" tag } { "model" model } }
77{ $description "Creates a " { $link model } " tuple from the given triangles tag, source set and vertices pair." } ;
78
79HELP: mesh>triangles
80{ $values { "sources" sequence } { "vertices" pair } { "mesh-tag" tag } { "models" sequence } }
81{ $description "Creates a sequence of models from the triangles in the mesh tag." } ;
82
83HELP: mesh>models
84{ $values { "mesh-tag" tag } { "models" sequence } }
85{ $description "Converts a triangle mesh to a set of models suitable for rendering with OpenGL." } ;