1 /**
  2  * The Render Engine
  3  * HostComponent
  4  *
  5  * @fileoverview A component which allows chaining of {@link HostObject HostObjects} for
  6  *               complex object creation.
  7  *
  8  * @author: Brett Fattori (brettf@renderengine.com)
  9  * @author: $Author: bfattori $
 10  * @version: $Revision: 1555 $
 11  *
 12  * Copyright (c) 2011 Brett Fattori (brettf@renderengine.com)
 13  *
 14  * Permission is hereby granted, free of charge, to any person obtaining a copy
 15  * of this software and associated documentation files (the "Software"), to deal
 16  * in the Software without restriction, including without limitation the rights
 17  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 18  * copies of the Software, and to permit persons to whom the Software is
 19  * furnished to do so, subject to the following conditions:
 20  *
 21  * The above copyright notice and this permission notice shall be included in
 22  * all copies or substantial portions of the Software.
 23  *
 24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 29  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 30  * THE SOFTWARE.
 31  *
 32  */
 33 
 34 // The class this file defines and its required classes
 35 R.Engine.define({
 36     "class":"R.components.logic.Host",
 37     "requires":[
 38         "R.components.Logic",
 39         "R.engine.GameObject",
 40         "R.struct.HashContainer"
 41     ]
 42 });
 43 
 44 /**
 45  * @class A component that can execute game objects.  Allows embedding
 46  *        of multiple objects into one object.  This is logically
 47  *        a method to embed further {@link R.engine.GameObject GameObjects} within
 48  *        an existing <tt>R.engine.GameObject</tt>.
 49  *
 50  * @param name {String} The name of the component
 51  * @param [priority=1.0] {Number} The priority of this component
 52  * @extends R.components.Logic
 53  * @constructor
 54  * @description Creates a <tt>R.components.Host</tt> which can contain {@link R.engine.GameObject GameObjects}.
 55  *              This allows a component to embed other game objects within it.  Each time the
 56  *              component is executed, each game object will be given a chance to update as well.
 57  */
 58 R.components.logic.Host = function () {
 59     "use strict";
 60     return R.components.Logic.extend(/** @scope R.components.logic.Host.prototype */{
 61 
 62         objects:null,
 63 
 64         /**
 65          * @private
 66          */
 67         constructor:function (name, priority) {
 68             this.base(name, priority || 1.0);
 69             this.objects = R.struct.HashContainer.create();
 70         },
 71 
 72         /**
 73          * Releases the component back into the object pool.  See {@link R.engine.PooledObject#release}
 74          * for more information.
 75          */
 76         release:function () {
 77             this.base();
 78             this.objects = null;
 79         },
 80 
 81         /**
 82          * Destroys the container which refers to the game objects.
 83          */
 84         destroy:function () {
 85             this.objects.destroy();
 86             this.base();
 87         },
 88 
 89         /**
 90          * Add a {@link R.engine.GameObject} to the component to be processed when
 91          * this component is executed.  Objects will be updated in the order in
 92          * which they are added.
 93          *
 94          * @param name {String} A unique name to refer to the object by
 95          * @param obj {R.engine.GameObject} The game object reference
 96          */
 97         add:function (name, obj) {
 98             Assert((obj instanceof R.engine.GameObject), "You can only add GameObject to a Host component");
 99             this.objects.add(name.toUpperCase(), obj);
100         },
101 
102         /**
103          * Retrieve the {@link R.engine.GameObject} that is associated with the
104          * given name from the component.
105          *
106          * @param name {String} The unique name of the object
107          * @return {R.engine.GameObject}
108          */
109         get:function (name) {
110             return this.objects.get(name.toUpperCase());
111         },
112 
113         /**
114          * Remove the game object from the component.
115          *
116          * @param obj {R.engine.GameObject} The game object reference
117          * @return {R.engine.GameObject} The object which was removed
118          */
119         remove:function (obj) {
120             return this.objects.remove(obj);
121         },
122 
123         /**
124          * Update each of the game objects within this component.  The order
125          * in which game objects are updated is equivalent to the order in which
126          * the objects were added.
127          *
128          * @param renderContext {R.rendercontexts.AbstractRenderContext} The rendering context
129          * @param time {Number} The engine time in milliseconds
130          * @param dt {Number} The delta between the world time and the last time the world was updated
131          *          in milliseconds.
132          */
133         execute:function (renderContext, time, dt) {
134             var objs = this.objects.getObjects();
135             for (var c in objs) {
136 
137                 // Make sure the game object's render context matches
138                 // this component's game object's context
139                 if (objs[c].getRenderContext() == null) {
140                     objs[c].setRenderContext(renderContext);
141                     R.debug.Console.info(this.getGameObject().getId() + "[" + this.getName() + "]: SetRenderContext '" + renderContext.getId() + "'");
142                 }
143 
144                 objs[c].update(renderContext, time, dt);
145             }
146         }
147     }, /** @scope R.components.logic.Host.prototype */{
148         /**
149          * Get the class name of this object
150          *
151          * @return {String} "R.components.logic.Host"
152          */
153         getClassName:function () {
154             return "R.components.logic.Host";
155         }
156     });
157 }