/home/lindsay/xeolabs/xeogl-next/xeogl/examples/js/models/buildableModel.js

xeogl / API Docs

API Docs for:

File: /home/lindsay/xeolabs/xeogl-next/xeogl/examples/js/models/buildableModel.js

  1. /**
  2.  A **BuildableModel** is a {{#crossLink "Model"}}{{/crossLink}} that provides a "stateful builder" API through which you can
  3.  procedurally generate xeogl content.
  4.  
  5.  <a href="../../examples/#models_generation_city"><img src="http://i.giphy.com/l0HlPJO1AN01Lz27e.gif"></img></a>
  6.  
  7.  ## Overview
  8.  
  9.  * A BuilderModel implements the [Builder pattern](https://en.wikipedia.org/wiki/Builder_pattern).
  10.  * Create various assets within a BuilderModel, such as {{#crossLink "Geometry"}}Geometries{{/crossLink}}
  11.  and {{#crossLink "Material"}}Materials{{/crossLink}}, then create {{#crossLink "Mesh"}}Meshes{{/crossLink}} that use those assets.
  12.  * The BuilderModel then owns those components and will destroy them when you
  13.  call its {{#crossLink "BuildableModel/clear:method"}}clear(){{/crossLink}} or {{#crossLink "Component/destroy:method"}}destroy(){{/crossLink}} methods.
  14.  * A BuildableModel can be transformed within World space by attaching it to a {{#crossLink "Transform"}}{{/crossLink}}.
  15.  * A BuildableModel provides its World-space boundary as a {{#crossLink "Boundary3D"}}{{/crossLink}}.
  16.  
  17.  ## Examples
  18.  
  19.  * [Generating a city with a BuildableModel](../../examples/#models_generation_city)</li>
  20.  
  21.  ## Usage
  22.  
  23.  A BuildableModel containing ten textured boxes with random sizes and positions:
  24.  
  25.  ````javascript
  26.  var model = new xeogl.BuildableModel();
  27.  
  28.  // Add a BoxGeometry asset
  29.  buildableModel.createAsset("boxGeometry", {
  30.      type: "xeogl.BoxGeometry"
  31.  });
  32.  
  33.  // Add a PhongMaterial asset
  34.  buildableModel.createAsset("gridMaterial", {
  35.      type: "xeogl.PhongMaterial",
  36.      ambient: [0.9, 0.3, 0.9],
  37.      shininess: 30,
  38.      diffuseMap: {
  39.          src: "textures/diffuse/gridMaterial.jpg"
  40.      }
  41.  });
  42.  
  43.  // Set the BoxGeometry asset as the current geometry
  44.  buildableModel.setGeometry("boxGeometry");
  45.  
  46.  // Set the PhongMaterial asset as the current material
  47.  buildableModel.setMaterial("gridMaterial");
  48.  
  49.  // Build ten meshes with random sizes and positions,
  50.  // that each get the current geometry and material
  51.  for (var i = 0; i < 10; i++) {
  52.  
  53.      buildableModel.setScale(Math.random() * 10 + 1, Math.random() * 10 + 1, Math.random() * 10 + 1);
  54.      buildableModel.setPosition(Math.random() * 100 - 50, Math.random() * 100 - 50, Math.random() * 100 - 50);
  55.  
  56.      buildableModel.createMesh();
  57.  }
  58.  ````
  59.  
  60.  @class BuildableModel
  61.  @module xeogl
  62.  @submodule models
  63.  @constructor
  64.  @param [scene] {Scene} Parent {{#crossLink "Scene"}}Scene{{/crossLink}} - creates this BuildableModel in the default
  65.  {{#crossLink "Scene"}}Scene{{/crossLink}} when omitted.
  66.  @param [cfg] {*} Configs
  67.  @param [cfg.id] {String} Optional ID, unique among all components in the parent {{#crossLink "Scene"}}Scene{{/crossLink}}, generated automatically when omitted.
  68.  @param [cfg.entityType] {String} Optional entity classification when using within a semantic data model. See the {{#crossLink "Object"}}{{/crossLink}} documentation for usage.
  69.  @param [cfg.meta] {String:Object} Optional map of user-defined metadata to attach to this BuildableModel.
  70.  @param [cfg.position=[0,0,0]] {Float32Array} The BuildableModel's local 3D position.
  71.  @param [cfg.scale=[1,1,1]] {Float32Array} The BuildableModel's local scale.
  72.  @param [cfg.rotation=[0,0,0]] {Float32Array} The BuildableModel's local rotation, as Euler angles given in degrees.
  73.  @param [cfg.matrix=[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1] {Float32Array} The BuildableModel's local transform matrix. Overrides the position, scale and rotation parameters.
  74.  @extends Model
  75.  */
  76. {
  77.  
  78.     xeogl.BuildableModel = class xeoglBuildableModel extends xeogl.Model {
  79.  
  80.         init(cfg) {
  81.             super.init(cfg);
  82.             this._initState();
  83.         }
  84.  
  85.         _initState() {
  86.             this._state = {
  87.                 material: null,
  88.                 geometry: null,
  89.                 pos: xeogl.math.vec3([0, 0, 0]),
  90.                 scale: xeogl.math.vec3([1, 1, 1]),
  91.                 angles: xeogl.math.vec3([0, 0, 0]),
  92.                 axis: [0, 1, 2],
  93.                 colorize: xeogl.math.vec3([1, 1, 1]),
  94.                 assetCfgs: {},
  95.                 assets: {}
  96.             };
  97.         }
  98.  
  99.         /**
  100.          * Adds an asset to this BuildableModel.
  101.          *
  102.          * The asset is given as a configuration object, to be lazy-instantiated as soon as an mesh is built from
  103.          * it with {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  104.          *
  105.          * #### Usage
  106.          *
  107.          * Adding a {{#crossLink "PhongMaterial"}}{{/crossLink}} asset with ID "gridMaterial":
  108.          *
  109.          * ````javascript
  110.          * buildableModel.createAsset("gridMaterial", {
  111.          *     type: "xeogl.PhongMaterial",
  112.          *     ambient: [0.9, 0.3, 0.9],
  113.          *     shininess: 30,
  114.          *     diffuseMap: {
  115.          *         src: "textures/diffuse/uvGrid2.jpg"
  116.          *     }
  117.          * });
  118.          * ````
  119.          *
  120.          * Adding a {{#crossLink "BoxGeometry"}}{{/crossLink}} asset with ID "boxGeometry":
  121.          *
  122.          * ````javascript
  123.          * buildableModel.createAsset("boxGeometry", {
  124.          *     type: "xeogl.BoxGeometry",
  125.          *     xSize: 1.0,
  126.          *     ySize: 1.0,
  127.          *     zSize: 1.0
  128.          * });
  129.          * ````
  130.          *
  131.          * @method createAsset
  132.          * @param {String|Number} assetId A unique ID for the asset.
  133.          * @param {*} cfg Configuration object for the asset.
  134.          */
  135.         createAsset(assetId, cfg) {
  136.             this._state.assetCfgs[assetId] = cfg;
  137.             delete this._state.assets[assetId];
  138.         }
  139.  
  140.         /**
  141.          * Selects the {{#crossLink "Geometry"}}{{/crossLink}} asset that will be added to
  142.          * each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created with
  143.          * {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  144.          *
  145.          * The given ID must belong to a {{#crossLink "Geometry"}}{{/crossLink}} asset that was added previously with
  146.          * {{#crossLink "BuildableModel/asset:method"}}asset(){{/crossLink}}.
  147.          *
  148.          * @method geometry
  149.          * @param {String|Number} assetId The asset ID.
  150.          */
  151.         setGeometry(assetId) {
  152.             this._state.geometry = assetId;
  153.         }
  154.  
  155.         /**
  156.          * Selects the {{#crossLink "Material"}}{{/crossLink}} asset that will be added to
  157.          * each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created with
  158.          * {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  159.          *
  160.          * The given ID must belong to a {{#crossLink "Material"}}{{/crossLink}} asset that was added previously with
  161.          * {{#crossLink "BuildableModel/asset:method"}}asset(){{/crossLink}}.
  162.          *
  163.          * @method setMaterial
  164.          * @param {String|Number} assetId The asset ID.
  165.          */
  166.         setMaterial(assetId) {
  167.             this._state.material = assetId;
  168.         }
  169.  
  170.         /**
  171.          * Sets the 3D position of each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created with
  172.          * {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  173.          *
  174.          * @method setPosition
  175.          * @param {Number} x Position on X-axis.
  176.          * @param {Number} y Position on Y-axis.
  177.          * @param {Number} z Position on Z-axis.
  178.          */
  179.         setPosition(x, y, z) {
  180.             this._state.pos[0] = x;
  181.             this._state.pos[1] = y;
  182.             this._state.pos[2] = z;
  183.         }
  184.  
  185.         /**
  186.          * Sets the 3D scale of each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created with
  187.          * {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  188.          *
  189.          * @method setScale
  190.          * @param {Number} x Scale on X-axis.
  191.          * @param {Number} y Scale on Y-axis.
  192.          * @param {Number} z Scale on Z-axis.
  193.          */
  194.         setScale(x, y, z) {
  195.             this._state.scale[0] = x;
  196.             this._state.scale[1] = y;
  197.             this._state.scale[2] = z;
  198.         }
  199.  
  200.         /**
  201.          * Sets the 3D Euler rotation angles for each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created
  202.          * with {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  203.          *
  204.          * @method setRotation
  205.          * @param {Number} x Angle on X-axis in degrees.
  206.          * @param {Number} y Angle on Y-axis in degrees.
  207.          * @param {Number} z Angle on Z-axis in degrees.
  208.          */
  209.         setRotation(x, y, z) {
  210.             this._state.angles[0] = x;
  211.             this._state.angles[1] = y;
  212.             this._state.angles[2] = z;
  213.         }
  214.  
  215.         /**
  216.          * Sets the order of 3D rotations for each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created
  217.          * with {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  218.          *
  219.          * #### Usage
  220.          *
  221.          * The X, Y and Z axis are identified as ````0, 1, 2```` respectively.
  222.          *
  223.          * ````Javascript
  224.          * buildableModel.setRotationAxis(0,1,2); // X, Y, Z
  225.          * buildableModel.setRotationAxis(2,0,1); // Z, X, Y
  226.          * buildableModel.setRotationAxis(1,2,0); // Y, Z, X
  227.          * ````
  228.          *
  229.          * @method setRotationAaxis
  230.          * @param {Number} a Indicates the first rotation axis.
  231.          * @param {Number} b Indicates the second rotation axis.
  232.          * @param {Number} c Indicates the third rotation axis.
  233.          */
  234.         setRotationAxis(a, b, c) {
  235.             this._state.axis[0] = a;
  236.             this._state.axis[1] = b;
  237.             this._state.axis[2] = c;
  238.         }
  239.  
  240.         /**
  241.          * Sets the RGBA colorize factors each {{#crossLink "Mesh"}}{{/crossLink}} subsequently created
  242.          * with {{#crossLink "BuildableModel/mesh:method"}}mesh(){{/crossLink}}.
  243.          *
  244.          * #### Usage
  245.          *
  246.          * ````Javascript
  247.          * buildableModel.setColorize(0.4, 0.4, 0.4, 1.0);
  248.          * ````
  249.          *
  250.          * @method setColorize
  251.          * @param {Number} r Indicates the amount of red.
  252.          * @param {Number} g Indicates the amount of green.
  253.          * @param {Number} b Indicates the amount of blue.
  254.          * @param {Number} z Indicates the alpha.
  255.          */
  256.         setColorize(r, g, b, a) {
  257.             this._state.colorize[0] = r;
  258.             this._state.colorize[1] = g;
  259.             this._state.colorize[2] = b;
  260.             this._state.colorize[3] = a;
  261.         }
  262.  
  263.         /**
  264.          * Creates an {{#crossLink "Mesh"}}{{/crossLink}} with whatever assets and states are currently
  265.          * set on this BuildableModel.
  266.          *
  267.          * @method createMesh
  268.          * @param {String|Number} [id] A unique ID for the new {{#crossLink "Mesh"}}{{/crossLink}}.
  269.          */
  270.         createMesh(id) {
  271.             var mesh = new xeogl.Mesh({
  272.                 id: id,
  273.                 material: this._getAsset(this._state.material),
  274.                 geometry: this._getAsset(this._state.geometry),
  275.                 scale: this._state.scale,
  276.                 position: this._state.pos,
  277.                 colorize: this._state.colorize
  278.             });
  279.             this._addComponent(mesh);
  280.             this.addChild(mesh, false); // Don't inherit state from this Model
  281.         }
  282.  
  283.         _getAsset(assetId) {
  284.             if (assetId === null) {
  285.                 return;
  286.             }
  287.             var asset = this._state.assets[assetId];
  288.             if (!asset) {
  289.                 var assetCfg = this._state.assetCfgs[assetId];
  290.                 if (!assetCfg) {
  291.                     this.error("Unknown asset: " + assetId);
  292.                     return;
  293.                 }
  294.                 asset = this.create(assetCfg);
  295.                 this._state.assets[assetId] = asset;
  296.                 this._addComponent(asset);
  297.             }
  298.             return asset;
  299.         }
  300.  
  301.         /**
  302.          * Removes all assets and {{#crossLink "Mesh"}}Meshes{{/crossLink}} from this BuildableModel.
  303.          * @method clear
  304.          */
  305.         clear() {
  306.             super.clear();
  307.             this._initState();
  308.         }
  309.  
  310.         /**
  311.          * Resets the state of this BuildableModel to defaults.
  312.          * @method reset
  313.          */
  314.         reset() {
  315.             this.setPosition(0, 0, 0);
  316.             this.setScale(1, 1, 1);
  317.             this.setRotation(0, 0, 0);
  318.             this.setRotationAxis(0, 1, 2);
  319.             this.setColorize(1, 1, 1, 1);
  320.             this.setMaterial(null);
  321.             this.setGeometry(null);
  322.         }
  323.     };
  324. }
  325.  
  326.