dreemgl/docs/api/guides/devguide/README.js

DreemGL is an open-source multi-screen prototyping framework for mediated environments, with a visual editor and shader styling for webGL and DALi runtimes written in JavaScript. As a toolkit for gpu-accelerated multiscreen development, DreemGL includes

Ext.data.JsonP.devguide({"guide":"<h1 id='devguide-section-developer%27s-guide-to-dreemgl'>Developer's Guide to DreemGL</h1>\n<div class='toc'>\n<p><strong>Contents</strong></p>\n<ul>\n<li>1. <a href='#!/guide/devguide-section-views'>Views</a>\n <ul>\n<li>1.1. <a href='#!/guide/devguide-section-adding-children-to-views-using-render-functions'>Adding Children to Views Using Render Functions</a>\n </li>\n<li>1.2. <a href='#!/guide/devguide-section-how-render-functions-work'>How Render Functions Work</a>\n </li>\n<li>1.3. <a href='#!/guide/devguide-section-adding-children-to-views-using-appendchild'>Adding Children to Views Using appendChild</a>\n </li>\n</ul></li>\n<li>2. <a href='#!/guide/devguide-section-classes'>Classes</a>\n </li>\n<li>3. <a href='#!/guide/devguide-section-attributes'>Attributes</a>\n <ul>\n<li>3.1. <a href='#!/guide/devguide-section-creating-attributes'>Creating Attributes</a>\n </li>\n<li>3.2. <a href='#!/guide/devguide-section-listening-to-changes'>Listening to Changes</a>\n </li>\n<li>3.3. <a href='#!/guide/devguide-section-using-attributes'>Using Attributes</a>\n </li>\n</ul></li>\n<li>4. <a href='#!/guide/devguide-section-styles'>Styles</a>\n <ul>\n<li>4.1. <a href='#!/guide/devguide-section-style-selectors'>Style Selectors</a>\n </li>\n<li>4.2. <a href='#!/guide/devguide-section-style-best-practices'>Style Best Practices</a>\n </li>\n</ul></li>\n<li>5. <a href='#!/guide/devguide-section-shaders'>Shaders</a>\n <ul>\n<li>5.1. <a href='#!/guide/devguide-section-how-do-shaders-work-with-view-attributes%3F'>How do shaders work with view attributes?</a>\n </li>\n<li>5.2. <a href='#!/guide/devguide-section-how-does-typing-work-in-shaders%3F'>How does typing work in shaders?</a>\n </li>\n<li>5.3. <a href='#!/guide/devguide-section-how-does-the-shader-compiler-work%3F'>How does the shader compiler work?</a>\n </li>\n<li>5.4. <a href='#!/guide/devguide-section-should-variables-be-on-the-view-or-on-the-shader%3F'>Should variables be on the view or on the shader?</a>\n </li>\n<li>5.5. <a href='#!/guide/devguide-section-can-i-write-custom-shaders%3F'>Can I write custom shaders?</a>\n </li>\n<li>5.6. <a href='#!/guide/devguide-section-how-do-i-use-texture-in-a-shader%3F'>How do I use texture in a shader?</a>\n </li>\n</ul></li>\n<li>6. <a href='#!/guide/devguide-section-adding-documentation-to-dreemgl'>Adding Documentation to DreemGL</a>\n <ul>\n<li>6.1. <a href='#!/guide/devguide-section-generating-documentation'>Generating Documentation</a>\n </li>\n</ul></li>\n</ul></div>\n\n<p>This guide is intended for developers who want to write applications or extend the DreemGL framework.</p>\n\n<p>DreemGL is an open-source multi-screen prototyping framework\nfor iOT with a visual editor and shader styling for webGL and DALi\nruntimes written in JavaScript. An overview of the framework is shown\nhere:</p>\n\n<p>![Architecture Image]\n(https://raw.githubusercontent.com/dreemproject/dreemgl/dev/docs/images/architecture.png)</p>\n\n<h2 id='devguide-section-views'>Views</h2>\n\n<p><a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/view.js\">view.js</a> is the baseclass of all visible items on screen.  It contains\nall attributes that are used by the render system to layout, and draw\na view. A <strong>view</strong> has a set of 'children' on this.children and a set of\n<strong>shaders</strong> that it iterates over to draw them.</p>\n\n<p>So if you look in\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/platform/webgl/devicewebgl.js\">system/platform/webgl/devicewebgl.js</a>,\nyou will see the main <code>drawpass</code>. The <code>doColor</code> method loops over the\nset of views that need layout, meaning the ones that need their\nmatrices set up, and then loops over the surfaces to draw them. To do\nthis, DreemGL uses a <code>drawpass</code> or a <code>render to texture</code> . The\n<code>drawpass</code> class holds the actual loop-over-views loop to then draw\nthe shaders.</p>\n\n<h3 id='devguide-section-adding-children-to-views-using-render-functions'>Adding Children to Views Using Render Functions</h3>\n\n<p>To add children to views, the recommended way is to use <code>render</code>\nfunctions which generate children based on state on properties. If you\ndo it this way, then <code>livereload</code> works. If you make the UI much more\nstateful by dynamically adding children using the <code>appendChild</code>\nfunction, then live reloading becomes much harder as described further on.</p>\n\n<p>Learning how to use the render functions is very important. For many\nsmaller scale datasets, it works great and is the recommended\nmethodology. For very large scale datasets, it is advisable to use\nthe typed-array api, where you essentially write your own renderer for\nvery large datasets.</p>\n\n<h3 id='devguide-section-how-render-functions-work'>How Render Functions Work</h3>\n\n<p>When the UI initializes, it calls <code>render</code> on the composition,\nreturning a tree. Then, the UI finds the screen it wants to show, and\nthen it calls <code>Render.process</code> (see\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/render.js\">system/base/render.js</a>)\non that screen.</p>\n\n<p>This will emit the <code>init</code> event on the screen, and call the <code>render</code>\nfunction on that screen. At that point, every widget in the tree will\nrecursively get <code>render</code> on itself called to determine its children.</p>\n\n<p><em>So how do render functions know when to re-render themselves?</em>\nIf you look at\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/render.js\">system/base/render.js</a>,\nyou will see that DreemGL 'watches' all the attribute getters on the\nobject it calls <code>render</code> on.</p>\n\n<p>So, this example:</p>\n\n<p><code>view({prop:10, render:function(){ return view({bla:this.prop}) }})</code></p>\n\n<p>creates an update bind between the <code>prop</code> on the parent view and its\n<code>render1 function. If that</code>prop<code>gets changed anywhere, 'render</code> will\nbe called again automatically.</p>\n\n<p>This is similar to how react works, except the 'state' object is put on the component in pieces.</p>\n\n<p><code>render</code> is relatively fast, and can be used to do a fair amount of\ndynamic UI with a <code>render</code> function. It is also incremental and\ncached, so if you just add an item at the end of a list, it is not\nvery expensive to just use the <code>render</code> function.</p>\n\n<h3 id='devguide-section-adding-children-to-views-using-appendchild'>Adding Children to Views Using appendChild</h3>\n\n<p>If you make the UI much more stateful by dynamically adding children\nusing the <code>appendChild</code> function, then live reloading becomes much\nharder. Unless you have a very good reason, we recommend that you <strong>do\nnot use</strong> <code>appendChild</code> and instead use the <code>render</code> functions.</p>\n\n<p>The reason you may need to use an <code>appendChild</code> function, is that if you call\na constructor of a view like this:</p>\n\n<p><code>view({props})</code></p>\n\n<p>it returns a view, but that view has not yet been initialized. <code>init</code>\nhas not been called on it yet, nor does it have <code>render</code> called on it\nyet. There are also other behind-the-scenes operations happening such as\nstyle application, which restricts the creation of views to be inside\nspecific scopes.</p>\n\n<h2 id='devguide-section-classes'>Classes</h2>\n\n<p>Classes are defined in a single file, using the following syntax:\n```\ndefine.class('$ui/view', function(require, exports, $ui$, label){\n        var mylib = require('./mylib')</p>\n\n<pre><code>    this.method = function(){\n    }\n\n    exports.staticmethod = function(){\n    }\n</code></pre>\n\n<p>})\n```</p>\n\n<p>Please note the 'require' syntax to specify the baseclass, and the $ui$ to switch directory in the dependency-class list.\nOther syntax: $$ - current directory, relative$dir$</p>\n\n<p>The prototype of the class is the 'this' of the function. Also note the two specially named arguments 'require' and 'exports' where they appear doesn't matter, but the name does:\n* exports is the class constructor function, which can hold the static methods.\n* require is simply the local instance of require if needed for normal requires.</p>\n\n<p>After the baseclass and dependencies, you can define attributes on a dreemclass.</p>\n\n<h2 id='devguide-section-attributes'>Attributes</h2>\n\n<p><strong>Attributes</strong> are special properties on an object. You can define them like this:\n<code>this.attributes={propname:Config({value:10})</code></p>\n\n<h3 id='devguide-section-creating-attributes'>Creating Attributes</h3>\n\n<p>To create attributes, define a magical attribute setter as shown in <a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/node.js\">node.js</a>.</p>\n\n<p><code>this.attributes = {}</code> is actually a function call. Using setters as\ninit calls allows DreemGL to create nested json and assign them to\nclasses all at once: <code>{attributes:{}}</code></p>\n\n<p>Again, all of these things are defined in\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/node.js\">node.js</a>.</p>\n\n<p>The way to create them in a class is to assign an object to this.attributes. The setter of 'attributes' will handle creating all the attributes on the class for you. Types of attributes are automatically inferred if assigned with a plain value, but can also be configured using a <code>Config({meta:'hello'})</code> object. Assigning a Config object to any existing attribute also refines its settings.</p>\n\n<p>Options for the config attribute are:\n<code>\n        type:vec2,float,String\n        value:0.4,vec2(3),\"hello\"\n        meta:'metadataforeditor'\n        persist:true // make sure the attribute survives a livereload / rerender\n</code>\n<code>\nthis.attributes = {\n        propfloat: 1.0,\n        propstring: \"HELLO\",\n        propcustom: Config({type:vec2})\n}\n</code></p>\n\n<p>Attributes are also automatically created if you pass them to the constructor function. <code>view({myprop:10})</code> automatically creates the myprop attribute.</p>\n\n<h3 id='devguide-section-listening-to-changes'>Listening to Changes</h3>\n\n<p>Attributes can listen to changes, as they are implemented with an\nunderlying getter/setter (see\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/node.js\">system/base/node.js</a>).</p>\n\n<p>An example of an attribute being assigned 'listeners' can be seen in <code>borderradius</code> in\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/view.js\">view.js</a>.</p>\n\n<p>The reason DreemGL uses these setters is that there is a very clean json mapping like so:</p>\n\n<p><code>view({someattrib:function(){ } })</code></p>\n\n<p>which is the same as:</p>\n\n<p><code>this.someattrib = function(){}</code></p>\n\n<p>The use of listeners forms the core eventhandling system. When a value of an attribute changes, using a simple assignment:\n<code>\nthis.attr = 10\n````\nThis will fire all the listeners to this attribute. Adding listeners to attributes is advised to use the onattr (on prefix) syntax.\n</code>\nthis.onattr = function(event){\n        // event object contains value, old, type, etc\n}\n```</p>\n\n<p>Attribute listeners are called parent-on-up in the prototype hierarchy, and each prototypelevel only has one 'onattr' slot, since this is a normal property. Emitting an event on an attribute can be done by assigning to it, but also using the emit syntax. This object goes to all the listeners as an argument:\n<code>\nthis.emit('attr',{type:'myown'})\n</code>\nIt is also possible to mark values going into a setter using the Mark wrapper:\n<code>\nthis.attr = Mark(15, true) // or plainly Mark(15)\n</code>\nThis 'mark' is passed into the event object to all the listener as the mark property. Using this it is possible to break infinite feedback loops like so:\n<code>\nthis.onattr = function(event){\n        if(event.mark) return // someone did an attribute assign using the Mark\n}\n</code></p>\n\n<p>It is also possible to use <code>addListener</code>, this adds a list of\nlisteners which are not the same as the onattr (on prefix) slots on\nthe prototype chain. However this is exceedingly rare:\n```\nthis.addListener('attr', function(event){</p>\n\n<p>})\n```</p>\n\n<h3 id='devguide-section-using-attributes'>Using Attributes</h3>\n\n<p>The recommended usage methodology is as follows.</p>\n\n<ol>\n<li>Define an attribute:</li>\n</ol>\n\n\n<p><code>this.attributes = {prop:Config({...})}</code></p>\n\n<p>Note that the <code>Config</code> wrapper allows you to store values in the\nattribute config object, which can contain type, name, meta data for\nthe visual editor, etc.</p>\n\n<ol>\n<li>Define an attribute on a view. The arguments to the <code>view({...})</code> is the same object that is assigned\nto the <code>this.attributes = {}</code> setter of the instance, which is what\nlets you define an attribute on a view as follows:</li>\n</ol>\n\n\n<p><code>view({prop:10})</code></p>\n\n<p>This creates an attribute called <code>prop</code>, of type <code>float</code> automatically,</p>\n\n<ol>\n<li>Put a listener on the attribute and assign a function to it. In\nthis example, we have created an attribute called <code>prop</code>. Now lets\nput a listener on it and assign a function to it as follows:</li>\n</ol>\n\n\n<p><code>this.prop = function(){ }</code> is a shortcut for\n<code>this.addListener('prop', function(){})</code> if it's an attribute.</p>\n\n<p>It's a shortcut for <code>addlistener</code> with one side note: if you assign to\nthe property again with a new function, it will <em>remove the old\nlistener and set the new one</em>.</p>\n\n<p>This makes it very easy to hook/unhook functions on listeners. And, it\nmeans you can write your components in a very clear and simple way, such as:</p>\n\n<p><code>this.click = function(){ }</code></p>\n\n<p>Attributes are also automatically readable in shaders. So, the following example:</p>\n\n<p><code>view({prop:10, bg:{color(){ return prop*vec4(1) }}})</code></p>\n\n<p>makes a view where the background shader reads a property all without\nthe need for declaring/creating attributes.</p>\n\n<p>Event flow follows the inheritance structure of\nthe class. Base classes get their listeners called first as you can\nsee in the implementation of\n<a href=\"https://github.com/dreemproject/dreemgl/blob/dev/system/base/node.js\">node.js</a>.</p>\n\n<h2 id='devguide-section-styles'>Styles</h2>\n\n<p>DreemGL does not implement CSS for styling components but instead relies on JavaScript notation for styling views and UI widgets. Each visual object in DreemGL has a <em>style</em> attribute, which can be set inside the class or on an instance. There are 3 different ways how styles can be set in DreemGL:</p>\n\n<ol>\n<li>Add style to composition using <code>this.style = {...}</code> inside the composition class body. Styles in compositions apply to all screens, views, and UI widgets on all screens.</li>\n<li>Add style to class using <code>this.style = {...}</code>.</li>\n<li>Add style to instance inside a render function of a screen or view (or subclass of one of these).</li>\n</ol>\n\n\n<p>A code example will make things clearer. Let's take a look at the style1.js composition. There are two style sheets in this composition: One on the composition itself, then a class style in the embedded <em>redview</em> class.</p>\n\n<p><a href=\"/docs/examples/devguide/style1\" target=\"_blank\" data-example=\"DreemGL Style Example|436|128\">http://localhost:2000/docs/examples/devguide/style1</a></p>\n\n<pre><code class=\"javascript\">define.class('$server/composition', function ($ui$, screen, view, label){\n    this.style = {\n        view: {\n            bgcolor: 'orange',\n            margin: 10\n        },\n        label: {\n            fgcolor: 'blue'\n        }\n    }\n\n    // simple view subclass for testing styles inside a class\n    define.class(this, \"redview\", \"$ui/view\", function() {\n        this.bgcolor = \"red\";\n        this.style = {\n            view: {\n                w: 70,\n                h: 70,\n                bgcolor: 'green'\n            }\n        }\n        this.render = function() {\n            return [ view() ];\n        }\n    })\n\n    this.render = function(){\n        return [\n            screen({\n                    name:\"default\",\n                    clearcolor: 'white',\n                    flexdirection: 'row'\n                },\n\n                // styles get applied to these views\n                view({ name: 'v1', w: 50, h: 50, bgcolor: 'gray' })\n                ,this.redview({ name: 'redview1', w: 100, h: 100 })\n                ,label({ name: 'l1', text: 'label1', fgcolor: 'black'})\n                ,view({ name: 'v2', h: 50 }\n                    ,label({ name: 'l2', text: 'label2'})\n                )\n            )\n        ];\n    }\n})\n</code></pre>\n\n<p><em>Screenshot: /docs/examples/devguide/style1 compostion running</em></p>\n\n<p><img src=\"https://raw.githubusercontent.com/dreemproject/dreemgl/dev/docs/images/devguide-style1-screenshot.png\" width=\"436\" height=\"128\"/></p>\n\n<p>Let's analyse this composition:</p>\n\n<ul>\n<li>There is a style for the view class defined in the composition stylesheet, which sets attributes x, y, and bgcolor.</li>\n<li>The embedded class <em>redview</em> - a subclass of view - has a class stylesheet, which will be applied to all children of <em>redview</em> instances.</li>\n<li>The compositions render function generates a screen, with four views as direct children: view with name <code>v1</code>, redview with name <code>redview1</code>, label with name <code>l1</code>, view with name <code>v2</code>. The last view has a child label with name <code>l2</code>.</li>\n</ul>\n\n\n<p>Explanation of styles applied to each visual object:</p>\n\n<p><strong>screen.name='default':</strong> No style applied.</p>\n\n<p><strong>view.name='v1':</strong></p>\n\n<ul>\n<li> <code>margin: 10</code> from composition stylesheet</li>\n<li> <code>bgcolor: 'orange'</code> from composition stylesheet is overwritten by inline bgcolor attribute value.</li>\n</ul>\n\n\n<p><strong>this.redview.name='redview1':</strong></p>\n\n<ul>\n<li> <code>bgcolor</code> is set in class body without style. No other style is applied.</li>\n</ul>\n\n\n<p><strong>this.redview.name='redview1 - inner child view'</strong></p>\n\n<ul>\n<li> <code>margin: 10</code> from composition stylesheet</li>\n<li> <code>w: 70, h:70</code> from class stylesheet of <em>redview</em> class.</li>\n</ul>\n\n\n<p><strong>label.name='l1'</strong>: No style applied.</p>\n\n<p><strong>view.name='v2':</strong></p>\n\n<ul>\n<li> <code>bgcolor: 'orange', margin: 10</code> from composition stylesheet</li>\n</ul>\n\n\n<p><strong>label.name='l2'</strong>:</p>\n\n<ul>\n<li> <code>fgcolor: 'blue'</code> from composition stylesheet</li>\n</ul>\n\n\n<p>DreemGL supports a mechanism to assign stylesheet values to class instances using a limited number of selectors, which are described in the next section.</p>\n\n<h3 id='devguide-section-style-selectors'>Style Selectors</h3>\n\n<p>DreemGL supports the following selectors for applying styles to objects:</p>\n\n<table>\n<thead>\n<tr>\n<th> Selector </th>\n<th> Example </th>\n<th> Description </th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td> <code>$</code> </td>\n<td> <code>style = { $: { bgcolor: 'red' } }</code> </td>\n<td> <strong>Global Selector:</strong> Applied to all visual objects which are children or descendants of the component </td>\n</tr>\n<tr>\n<td> <code>{class}</code> </td>\n<td> <code>style = { label{ fgcolor: 'red' }</code> will be applied to <code>label({})</code> </td>\n<td> <strong>Class name:</strong> Applies to all instances of that class. </td>\n</tr>\n<tr>\n<td> <code>class_style</code> </td>\n<td> <code>style = { label_largeLabel{ fgcolor: 'red' }</code> will be applied to <code>label({class:'largeLabel'})</code> </td>\n<td> <strong>C</strong>lass name with attribute class='value'**  Applied to all instances of that class with the attribute <code>class</code> set to the same value. </td>\n</tr>\n<tr>\n<td> <code>style = {}</code> </td>\n<td> <code>button: { label: {margin:[11,1,1,1]} }</code> will be applied to the view structure <code>button({}, label({}))</code> </td>\n<td> <strong>Class and view child with class:</strong> Applied to all instances of that class with the attribute <code>class</code> set to the same value. </td>\n</tr>\n</tbody>\n</table>\n\n\n<p>Selecting objects through ID values is not not supported in DreemGL.</p>\n\n<h3 id='devguide-section-style-best-practices'>Style Best Practices</h3>\n\n<ul>\n<li>Composition wide styles should be put unto the composition directly.</li>\n<li>For classes or UI widgets, add a style inside the class definition. Developers using those classes or widgets can override the stylesheet feels in their own compositions.</li>\n<li>If you want to style views inside complex UI widgets, you can select whole structures of views in a style, e.g. <code>button: { label: {margin:[11,1,1,1]} }</code>.</li>\n<li>Be careful with style definitions on screens: These are a special case, since the values will only get applied to classes or instances which contain a render function.</li>\n</ul>\n\n\n<h2 id='devguide-section-shaders'>Shaders</h2>\n\n<p>Each view contains several shaders (such as <code>bg</code>, <code>border</code>) which can be assigned\nto a specific shader class. Views may turn on shaders when certain\nfeatures are enabled, for example:\n<code>hardrect</code> is assigned to <code>this.bg</code> if <code>this.borderradius</code> is <code>square</code>. This keeps performance fast by default.</p>\n\n<h3 id='devguide-section-how-do-shaders-work-with-view-attributes%3F'>How do shaders work with view attributes?</h3>\n\n<p><code>redraw()</code> is called whenever a view changes an attribute that a shader is bound to. This causes the new value to be used in the shader.</p>\n\n<h3 id='devguide-section-how-does-typing-work-in-shaders%3F'>How does typing work in shaders?</h3>\n\n<p>All data passed to shaders must have an explicit type. Dreemgl provides a few mechanisms to make this convenient.</p>\n\n<p>Type information specified on view attributes is automatically used. If a type can't be determined, type inferencing is used.</p>\n\n<p>Dreemgl also provides a mechanism to create structs:</p>\n\n<pre><code>// define a custom struct for use later\nthis.vertexstruct =  define.struct({\n pos:vec3,\n color:vec4,\n id: float\n})\n\n// make an instance of vertexstruct\nthis.mesh = this.vertexstruct.array();\n\n// push values onto the struct instance in the order they were declared in this.vertexstruct\nthis.mesh.push(pos, color, id)\n</code></pre>\n\n<p>Builtin <code>structs</code> use the same mechanism, e.g. <code>vec2()</code> is really an instance of <code>define.struct</code>, see\n<a href=\"https://github.com/dreemproject/dreemgl/blob/master/system/base/define.js\">system/base/define.js</a>.</p>\n\n<h3 id='devguide-section-how-does-the-shader-compiler-work%3F'>How does the shader compiler work?</h3>\n\n<p>The shader compiler lives on a baseclass of all the shaders, at\n<a href=\"https://github.com/dreemproject/dreemgl/blob/master/system/base/shader.js\">system/base/shader.js</a>.\nEvery time you extend a shader class it will run the js code-compiler\nto generate a pixel/vertexshader from that shader class with a hook.\nSo, every level of the shader prototype chain has a fully-generated\nset of shaders that you can place into a GL context.</p>\n\n<p>The shader compiler also will turn function references on its objects\ninto getter/setters that will flag a shader ‘dirty’ so it knows when\nextending it actually made it dirty.  If you just extend a shader and\nonly overload uniforms, it wont flag dirty.  The shader compiler knows\nhow to walk js object structures, and you can reference values on the\nshader object itself and the view.  It will only dynamically listen to\nvalues on the view (via the attribute system).</p>\n\n<p><code>this.style</code> can make this more efficient. If you override <code>bg</code> in an\ninstance it is slow. However, <code>this.style</code> allows instances with\nspecial overrides to create an interim class, allowing for compilation\nand faster instancing. In this way, style properties end up in the\nprototype and can still be overridden on a per-instance basis.</p>\n\n<h3 id='devguide-section-should-variables-be-on-the-view-or-on-the-shader%3F'>Should variables be on the view or on the shader?</h3>\n\n<p>For interactivity variabes, like <code>pixelSize</code>, you should put variables on the\nview and access them in the shader.  For shader-specific functions and\nvariables, it is fine to access them directly in the shader, but you\nwill not get automatic listeners and therefore redraw.</p>\n\n<p>Example: You want to control <code>pixelSize</code> in a <code>mouseleftup</code> function</p>\n\n<p>To do this, you would put variables on the view, and access them in the shader as <code>view.pixelSize</code>.\nManipulating them using <code>this.pixelSize =...</code> allows the shader to bind itself to <code>view.pixelSize</code> via a listener\nso that you get an automatic redraw if you change it.</p>\n\n<h3 id='devguide-section-can-i-write-custom-shaders%3F'>Can I write custom shaders?</h3>\n\n<p>Yes. If you want to write custom shaders you need to pick the shader you will subclass OR use <code>bgcolorfn</code>.\nWe recommend that you make a new shader class on a new view class with custom geometry to build most widgets.</p>\n\n<p>You can also freely inherit it instances, but if you intend to instance many of these, then it makes more sense to put it in a class.</p>\n\n<h3 id='devguide-section-how-do-i-use-texture-in-a-shader%3F'>How do I use texture in a shader?</h3>\n\n<p>Example: You want to use <code>bgimage</code> resource image as texture in <code>bg</code>'s color function</p>\n\n<p>Image objects are automatically converted to texture objects, so you can do the following:\n<code>`\nmytexture:require('./mytexture.jpg')\ncolor:function(){\n   return mytexture.sample(...)\n}\n</code></p>\n\n<h1 id='devguide-section-documentation'>Documentation</h1>\n\n<p>DreemGL provides an <a href=\"http://docs.dreemproject.org/docs/api/index.html#!/api\">API reference</a>, a\n<a href=\"http://docs.dreemproject.org/docs/api/index.html#!/guide/devguide\">Developer's Guide</a>,\nand guides for all components, including the visual layout toolkit,\nthe flow graph, and IoT integration. See the dreemproject server for a\n<a href=\"http://docs.dreemproject.org/docs/api/index.html#!/guide\">listing of all guides</a>.</p>\n\n<h2 id='devguide-section-adding-documentation-to-dreemgl'>Adding Documentation to DreemGL</h2>\n\n<p>DreemGL can generate documentation automatically from all the code in\nits system. Best practices encourage commenting code to improve raedability and maintainability. There are simple rules for adding comments to be included in the API documentation:</p>\n\n<ul>\n<li>To document a class, add a comment immediately after the opening function definition as shown:</li>\n</ul>\n\n\n<pre><code>define.class(\"$server/service\", function (require) {\n        // The iot class makes it very easy to connect to a wide variety of devices including\n        // SmartThings, Philips Hue and many more.\n        //\n        // IMPORTANT: see /examples/components/iot/README.md for setup instructions.\n        this.__thingmodel = {}\n        ...\n</code></pre>\n\n<ul>\n<li>To document an attribute, place the comment immediately <strong>before</strong> it as shown:</li>\n</ul>\n\n\n<pre><code>this.attributes = {\n       // Things: A list of things connected to the hub, automatically updated as new \n       //devices are discovered and their state changes.\n       things: Config({type: Array, value: [], flow:\"out\"}),\n\n       //Connected: If true, we are connected\n       connected: Config({type: Boolean, value: false, persist: true, flow:\"out\"})\n                 }\n</code></pre>\n\n<h3 id='devguide-section-generating-documentation'>Generating Documentation</h3>\n\n<p>To generate HTML documentation to ensure getting the latest, run the documentation builder:</p>\n\n<pre><code>            ./resources/bin/buiddocs\n</code></pre>\n\n<p>Then, the documentation will be visible here <a href=\"http://localhost:2000/docs/api/index.html\">/docs/api/index.html</a> when the server is running.</p>\n\n<iframe name='docrunner' style=\"width:1px; height:1px; border:0\" src=\"/docs/examples/docexamplerunner\"></iframe>\n\n","title":"Developer's Guide to DreemGL"});