object reference
From Wiki
(controls →lights) |
|||
| Line 3: | Line 3: | ||
=Overview= | =Overview= | ||
| − | + | {{main|JSOM}} | |
| − | + | More than anything else the "JSOM" schema as a creature of the popular JSON information exchange format. It is a JSON schema after all. JSON is a subset of the popular JavaScript programming language / ECMAScript standard. Minimalism is part and parcel of the JSON specification, which is another way of saying it is really very brief. Now is a good time to read about [[Wikipedia:JSON|JSON]] if you've never heard of it before. Any code in this document is JSON. It's pretty simple stuff, so JSOM by extension is pretty simple. That's good and bad. In case you are wondering why things are so simple, well that is why. OK! Moving on. | |
| + | |||
| + | The job of a JSOM (JSON) resource is to deliver graphics to an application that is probably programmed in JavaScript and running in a JavaScript engine of some kind, probably in a WWW browser. The application should be to display the graphics themselves, or combine them with other graphics in an interactive fashion if need be. This should be fast to do and not overly complicated. Animation is also very important. In theory every aspect of the JSOM resource should be able to be animated. Animation is not the same as interaction, however direct interaction and scripting is a desirable feature as well. | ||
| + | |||
| + | At the top level of a JSOM (JSON) resource you will find several named arrays of objects with various characteristic names; externals, templates, images, sounds, arrays, attributes, elements, semantics, materials, graphics, keyframes, keygroups, tracks, are all core to the specification. These are properly referred to as "namespaces" and they represent lists of items. The items themselves can contain sub-lists, so that the general structure of a namespace is more like an outline; Eg. item 0.1.1 refers to the first (zero-based) item at the top of the namespace, and then to the second item of its sub-list, and then to the second item of that item's sub-list. Items can be alternatively addressed by name, hence the term "namespace". Names within a namespace are assumed to be unique IDs, and are not hierarchically arranged, dotted or otherwise. Should a name collision occur, the previous holder of the name is effectively disappeared. | ||
==Items and Lists== | ==Items and Lists== | ||
| − | A JSOM item is a top-level object in the namespace hierarchy. So-named because they are always an object item of a JSON array. Items in an array do not have names, but you can assign a name to an item by giving | + | A JSOM item is a top-level object in the namespace hierarchy. So-named because they are always an object item of a JSON array. Items in an array do not have names, but you can assign a name to an item by giving it a ''name'' property. If an item contains a property with the same name of its namespace it will form a sub-list. For examples, an item in the ''graphics'' namespace, may contain a 'graphics' property of its own. The graphics property can then contain a list of "sub-graphics" and so on. The only thing to remember is that this kind of "nesting" is strictly limited to the operative namespace. You cannot for instance add a sub-list of "images" to an item in the graphics namespace. Any property that looks like a sub-list from another namespace is more than likely an [[#Indices, Index singular|#index]]. |
| − | ==Indices, Index | + | ==Indices, Index singular== |
| − | + | Indices are always properties of items, or part of a multi-index array that is itself a property. Each index refers to an item in one of the aforementioned namespaces, if any item at all. The name of the property pre-determines the namespace the index belongs to. If you don't know for sure, then you just have to look it up. Eg. an index property named 'sound' is going to be made up of indices which refer to the 'sounds' namespace. Pretty straightforward. Sometimes however the name of the property does not correspond letter by letter to the name of the namespace. That is what this reference is for. | |
| − | + | Now when indices are part an array, you can rest assured in the knowledge that all of the indices refer to items of just one of the multiple namespaces. And just to make things even simpler, you can always bet that a property is either an array (referring to 0 or more items) or not an array (referring to a single item) but never either or. The general rule is that if it would ever under any circumstance make sense to refer to more than one item by with a particular index property then that property is going to be a multi-index array. And before we are done with index arrays. In case you are wondering. An array may be the JSON null value, and it may be empty, and it may contain all null values, in any of these cases it is functionally equivalent to the index array not existing at all, which is the same as a non existent or null value non-array index property. | |
| − | + | Index values come in five interchangeable flavors: | |
| − | *A | + | *A null value; a ''null'' value, as described by the JSON specification. This is equivalent to the property not being defined in the first place. |
| − | * | + | *A single numeric value; a number indicating a top-level item of the relevant namespace at resource scope. Indexes cannot refer to a scope above the resource in which they are defined. See [[#External Resources]] for details. |
| − | * | + | *An array of number values; each subsequent number indicating an item in a sub-list as explained in the [[#Items and Lists]] section. So think comma notation rather than dot notation, but an outline nonetheless. |
| − | *An inline item; rather than indexing an item, a new item can alternatively be defined on the spot. Often this is the right idea. The only thing to | + | *A JSON character "string" index. This is a non-numeric name proper index, Ex. "left leg". These global to a namespace, any string literal works. |
| + | |||
| + | *An inline item; rather than indexing an item, a new item can alternatively be defined on the spot. Often this is the right idea. The only thing to bear in mind is that inline items can never be indexed into from other indexes. In case you are wondering, yes (in theory anyway) you can make a strictly serial JSOM resource consisting of pure inline notation. | ||
==External Resources== | ==External Resources== | ||
| − | The content of a JSOM resource can | + | The content of a JSOM resource can pull in outside JSOM resources through the power of external references. This is great both for organization and not putting all of your eggs into one basket; so to speak. A typical JSOM resource also includes non-JSOM resources: a reference to a [[PNG]] image for example; but these types of resources are dead ends as far as the JSOM schema is concerned, so we will not speak of them again. |
| − | The | + | The inclusion mechanism is one-way, "downstream", which is to say, a resource can include references to sub-resources, but not vice versa. There is a way around this limitation to some degree, namely through the judicious use of [[#Template Expansion|#Templates]] (keep reading) except for only that to say that a template refers to or includes anything would be a misconception of how the template mechanism actually works. |
| − | + | Unidirectional data flow is not a hard constraint. It is open to discussion. The arguments against it is a resource becomes more brittle if it can reference things upstream. An implementation would have to keep track of what is upstream in every context at the function level should the resource be shared. A special mechanism would need to be devised for upstream indexing. In general its comforting to know that your resources are functionally self contained units top to bottom. Conceptually a resource has direct knowledge of what lies below it. And no clue about what may lay above. | |
| − | Lazy indexing rules follow: whenever a reference is indexed. If an item in its sub-list is not indexed, then the index will indicate the first item included by the reference, or if that item is itself a reference, the first item included by that reference, and so on. This | + | What can be a reference? In practice any item may be a reference. A reference to what? A reference to the namespace of another file that bears the name of its own namespace. In fact the referenced namespace becomes one of those sub-lists we talked about. Except for one thing! A reference is a second-class item. Even though it has an address, it cannot be addressed; by an index for example. There is really no reason to do so. And either way the reference effectively becomes a placeholder for the first item of the included resource (or no item, if no such item exists) due to "lazy" indexing syntax. Maybe you've heard of it. Oh you haven't? |
| + | |||
| + | Lazy indexing rules follow: whenever a reference is indexed. If an item in its sub-list is not indexed, then the index will indicate the first item included by the reference, or if that item is itself a reference, the first item included by that reference, and so on. This can be referred to as "underflow" syntax--if you want. If the reference is the last item in its list then the remainder of a numeric index is used to index into the reference's sub-list. You can call this rule "overflow" syntax--if you must. Whether lazy indexing is technically "lazy" is up to debate. Dotted and named indexes may be unnecessary if you can refactor your resources about lazy indexing. You might even leverage such a scheme to shim in an extra layer of modularity to whatever it is you are doing. Just make sure you understand the rules and everyone involved understands when they are in play. | ||
==Template Expansion== | ==Template Expansion== | ||
| − | + | A [[#templates]] items is a generic bag of properties. In and of themselves without meaning. They are not true items though the same indexing rules apply. Depending on the semantics of the index in question the properties of the template are usually conferred in some way to some other item either directly and immediately or indirectly in a deferred fashion; as in the case of [[#keygroups]]. When the transfer of properties takes place, call it template expansion--or don't. | |
| − | + | The most basic example of expansion is the universal 'template' property. Every item may have this property. What it says is that on top of what properties the item has, it also wants the properties of the templates indexed. Expansion happens at the latest before the item is first considered in terms of its properties. Each template in the index is expanded from the first index to the last copy the properties of the templates into item doing the indexing. Yes of course templates can index other templates. And no, properties are never added together or anything. They are strictly overwritten. In JavaScript that usually means that only an object reference or similar sized literal gets copied. You can use this to your advantage to keep memory overhead to a minimum by sharing macro values. This can be a very effective strategy; especially since the key to speed in JavaScript is to avoid computation on the fly whenever you can help it: since its better at chewing up memory. In theory use of templates can amount to more memory being used too, but templates are not just for memory. You may use templates to better organize your resource or better organize the process through which you generate your resources. | |
| − | + | But wait, there is more! Templates are an integral part of the JSOM schema. Template indexes occur out in the wild. You will come across one sooner or later. You should just remember that templates do not do anything. And so if you see an index property inside of a template (remember indexes are local to the resource in which they appear) the indexes are not relevant to the resource in which the template appears. The indexes will become relevant when template expansion occurs, and that can happen inside of any resource that includes the resource that the template is part of. But what about [[#expand]] you ask? Glad that you asked... or ah no. Just kidding. | |
==Extensibility== | ==Extensibility== | ||
| − | + | You may come across properties not mentioned anywhere within this document. They may just be experimental, or they may be user defined properties. User defined properties are permitted. A resource might want to for instance, attach custom variables to a programmable [[shaders]], or the properties might be purely ancillary to the JSOM aware application layer. Either way there are no considerations as of yet concerning the collision of custom properties and those added by future versions of any particular JSOM specification or whatever. Just saying you can go wild if you gotta. | |
| − | |||
| − | |||
=Universal properties= | =Universal properties= | ||
Revision as of 01:46, 23 February 2012
This page is a complete (work in progress) object reference for the JSOM (JSON Sword-of-Moonlight Object Model) schema.
Contents
Overview
More than anything else the "JSOM" schema as a creature of the popular JSON information exchange format. It is a JSON schema after all. JSON is a subset of the popular JavaScript programming language / ECMAScript standard. Minimalism is part and parcel of the JSON specification, which is another way of saying it is really very brief. Now is a good time to read about JSON if you've never heard of it before. Any code in this document is JSON. It's pretty simple stuff, so JSOM by extension is pretty simple. That's good and bad. In case you are wondering why things are so simple, well that is why. OK! Moving on.
The job of a JSOM (JSON) resource is to deliver graphics to an application that is probably programmed in JavaScript and running in a JavaScript engine of some kind, probably in a WWW browser. The application should be to display the graphics themselves, or combine them with other graphics in an interactive fashion if need be. This should be fast to do and not overly complicated. Animation is also very important. In theory every aspect of the JSOM resource should be able to be animated. Animation is not the same as interaction, however direct interaction and scripting is a desirable feature as well.
At the top level of a JSOM (JSON) resource you will find several named arrays of objects with various characteristic names; externals, templates, images, sounds, arrays, attributes, elements, semantics, materials, graphics, keyframes, keygroups, tracks, are all core to the specification. These are properly referred to as "namespaces" and they represent lists of items. The items themselves can contain sub-lists, so that the general structure of a namespace is more like an outline; Eg. item 0.1.1 refers to the first (zero-based) item at the top of the namespace, and then to the second item of its sub-list, and then to the second item of that item's sub-list. Items can be alternatively addressed by name, hence the term "namespace". Names within a namespace are assumed to be unique IDs, and are not hierarchically arranged, dotted or otherwise. Should a name collision occur, the previous holder of the name is effectively disappeared.
Items and Lists
A JSOM item is a top-level object in the namespace hierarchy. So-named because they are always an object item of a JSON array. Items in an array do not have names, but you can assign a name to an item by giving it a name property. If an item contains a property with the same name of its namespace it will form a sub-list. For examples, an item in the graphics namespace, may contain a 'graphics' property of its own. The graphics property can then contain a list of "sub-graphics" and so on. The only thing to remember is that this kind of "nesting" is strictly limited to the operative namespace. You cannot for instance add a sub-list of "images" to an item in the graphics namespace. Any property that looks like a sub-list from another namespace is more than likely an #index.
Indices, Index singular
Indices are always properties of items, or part of a multi-index array that is itself a property. Each index refers to an item in one of the aforementioned namespaces, if any item at all. The name of the property pre-determines the namespace the index belongs to. If you don't know for sure, then you just have to look it up. Eg. an index property named 'sound' is going to be made up of indices which refer to the 'sounds' namespace. Pretty straightforward. Sometimes however the name of the property does not correspond letter by letter to the name of the namespace. That is what this reference is for.
Now when indices are part an array, you can rest assured in the knowledge that all of the indices refer to items of just one of the multiple namespaces. And just to make things even simpler, you can always bet that a property is either an array (referring to 0 or more items) or not an array (referring to a single item) but never either or. The general rule is that if it would ever under any circumstance make sense to refer to more than one item by with a particular index property then that property is going to be a multi-index array. And before we are done with index arrays. In case you are wondering. An array may be the JSON null value, and it may be empty, and it may contain all null values, in any of these cases it is functionally equivalent to the index array not existing at all, which is the same as a non existent or null value non-array index property.
Index values come in five interchangeable flavors:
- A null value; a null value, as described by the JSON specification. This is equivalent to the property not being defined in the first place.
- A single numeric value; a number indicating a top-level item of the relevant namespace at resource scope. Indexes cannot refer to a scope above the resource in which they are defined. See #External Resources for details.
- An array of number values; each subsequent number indicating an item in a sub-list as explained in the #Items and Lists section. So think comma notation rather than dot notation, but an outline nonetheless.
- A JSON character "string" index. This is a non-numeric name proper index, Ex. "left leg". These global to a namespace, any string literal works.
- An inline item; rather than indexing an item, a new item can alternatively be defined on the spot. Often this is the right idea. The only thing to bear in mind is that inline items can never be indexed into from other indexes. In case you are wondering, yes (in theory anyway) you can make a strictly serial JSOM resource consisting of pure inline notation.
External Resources
The content of a JSOM resource can pull in outside JSOM resources through the power of external references. This is great both for organization and not putting all of your eggs into one basket; so to speak. A typical JSOM resource also includes non-JSOM resources: a reference to a PNG image for example; but these types of resources are dead ends as far as the JSOM schema is concerned, so we will not speak of them again.
The inclusion mechanism is one-way, "downstream", which is to say, a resource can include references to sub-resources, but not vice versa. There is a way around this limitation to some degree, namely through the judicious use of #Templates (keep reading) except for only that to say that a template refers to or includes anything would be a misconception of how the template mechanism actually works.
Unidirectional data flow is not a hard constraint. It is open to discussion. The arguments against it is a resource becomes more brittle if it can reference things upstream. An implementation would have to keep track of what is upstream in every context at the function level should the resource be shared. A special mechanism would need to be devised for upstream indexing. In general its comforting to know that your resources are functionally self contained units top to bottom. Conceptually a resource has direct knowledge of what lies below it. And no clue about what may lay above.
What can be a reference? In practice any item may be a reference. A reference to what? A reference to the namespace of another file that bears the name of its own namespace. In fact the referenced namespace becomes one of those sub-lists we talked about. Except for one thing! A reference is a second-class item. Even though it has an address, it cannot be addressed; by an index for example. There is really no reason to do so. And either way the reference effectively becomes a placeholder for the first item of the included resource (or no item, if no such item exists) due to "lazy" indexing syntax. Maybe you've heard of it. Oh you haven't?
Lazy indexing rules follow: whenever a reference is indexed. If an item in its sub-list is not indexed, then the index will indicate the first item included by the reference, or if that item is itself a reference, the first item included by that reference, and so on. This can be referred to as "underflow" syntax--if you want. If the reference is the last item in its list then the remainder of a numeric index is used to index into the reference's sub-list. You can call this rule "overflow" syntax--if you must. Whether lazy indexing is technically "lazy" is up to debate. Dotted and named indexes may be unnecessary if you can refactor your resources about lazy indexing. You might even leverage such a scheme to shim in an extra layer of modularity to whatever it is you are doing. Just make sure you understand the rules and everyone involved understands when they are in play.
Template Expansion
A #templates items is a generic bag of properties. In and of themselves without meaning. They are not true items though the same indexing rules apply. Depending on the semantics of the index in question the properties of the template are usually conferred in some way to some other item either directly and immediately or indirectly in a deferred fashion; as in the case of #keygroups. When the transfer of properties takes place, call it template expansion--or don't.
The most basic example of expansion is the universal 'template' property. Every item may have this property. What it says is that on top of what properties the item has, it also wants the properties of the templates indexed. Expansion happens at the latest before the item is first considered in terms of its properties. Each template in the index is expanded from the first index to the last copy the properties of the templates into item doing the indexing. Yes of course templates can index other templates. And no, properties are never added together or anything. They are strictly overwritten. In JavaScript that usually means that only an object reference or similar sized literal gets copied. You can use this to your advantage to keep memory overhead to a minimum by sharing macro values. This can be a very effective strategy; especially since the key to speed in JavaScript is to avoid computation on the fly whenever you can help it: since its better at chewing up memory. In theory use of templates can amount to more memory being used too, but templates are not just for memory. You may use templates to better organize your resource or better organize the process through which you generate your resources.
But wait, there is more! Templates are an integral part of the JSOM schema. Template indexes occur out in the wild. You will come across one sooner or later. You should just remember that templates do not do anything. And so if you see an index property inside of a template (remember indexes are local to the resource in which they appear) the indexes are not relevant to the resource in which the template appears. The indexes will become relevant when template expansion occurs, and that can happen inside of any resource that includes the resource that the template is part of. But what about #expand you ask? Glad that you asked... or ah no. Just kidding.
Extensibility
You may come across properties not mentioned anywhere within this document. They may just be experimental, or they may be user defined properties. User defined properties are permitted. A resource might want to for instance, attach custom variables to a programmable shaders, or the properties might be purely ancillary to the JSOM aware application layer. Either way there are no considerations as of yet concerning the collision of custom properties and those added by future versions of any particular JSOM specification or whatever. Just saying you can go wild if you gotta.
Universal properties
This section lists properties which are common to all items regardless of namespace. These properties do not take on special meaning under any circumstances.
name
The name property permits an alternative to numeric indexing, with the downside of needing to have names handy or some mechanism for generating them on the fly. Names should be unique unless the behavior you are looking for is to overriding of a named item by the later/possible inclusion of an item with the same name. A name is a character "string".
template
The template property is an array of indexes into the #templates namespace. All properties from the templates indexed will be added, first to last, to the item containing the template property, including any template properties contained within the templates themselves. Note that properties overwrite one another. They are never added together in any way. A template is an array of indices.
ref
The ref property is a name that refers to an undetermined external resource. The item containing a ref property is a reference according to #External Resources however the resource in question is to be determined by the JSOM client application, which will use the value of ref to determine which resource to use. A ref is a character "string".
url
The url property is a numeric index into the #externals namespace. It results in a reference item that is determined entirely by the resource (compare to #ref above) at the time of its creation. A url is a singular index number.
<namespace>
Where <namespace> is the same name as the current namespace, Eg. graphics for the graphics names, images for the images namespace. This property is an array of namespace item objects which will form a sub-list beginning at the current item of the current namespace. A <namespace> is an array of namespace item objects.
Namespace properties
Each heading of this section is representative of a namespace of the same name. Each section below each heading describes the function of the namespace and the non-extended (see #Extensibility) properties that are meaningful to the items of that namespace.
