View source for XML 3D - BTS530/630 Project

= Programmers =

[[user:RealMarkP|Mark Paruzel]]<br />
[[user:YiShen|Yi Shen]]

= Canvas Object =

== History ==

Canvas elements simplify the drawing of custom pixels to the screen as well as the modification of these pixels in real-time. There have been numerous requests for a canvas tag inside HTML documents which provided custom draw ability inside XUL (A Cross-Platform drawing management library). Unfortunately, XUL is client side based which only allows the modification of web pages from the user’s endpoint. The Canvas Tag was originally developed in order to create modifications to the browser from the server end. An on-screen Canvas object is basically a wrapper around the XUL engine that allows the visual manipulation of pixels on the webpage. 

== Objective ==

The objective of Canvas was to provide a drawing interface inside the HTML document which website designers could use to create interactive content. It also allows the designers of the webpage to change the Canvas object on the fly using JavaScript or Python. The Canvas tag exposes the functionality of XUL with added security and safeguards to prevent damage to the client's computer.

= XML 3D Addition to Canvas =

== Rationale ==

The basis of the Canvas tag is to provide immediate drawing to the screen. The drawing can consist of regular 2D pixel manipulations as well as a proposed 3D model manipulation. In addition, it will provide a safe and simple application programming interface (API) to the OpenGL Layer. The OpenGL Layer is a library that handles the math required for 3D transformations. Unfortunately, OpenGL has the power to talk directly to the hardware therefore allowing direct manipulation of the hardware or possibly potential damage. Consequently, the OpenGL Layer will not be included in this project due to its complex nature and constant upkeep. In addition, the OpenGL API is extremely low-level and may be confusing when exposed to the internet. <br/> <br/>

However, the first step in creating a 3D Canvas element is to use a custom XML tag to specify the 3D objects on the screen as well as the drawing area available. In this case, the developer will be able to create 3D objects on the client's screen as well as provide logic to modify these objects in real-time. By using the Document Object Model (DOM) to interpret the XML language and retrieve the attributes of the objects, this causes the objects to be presented for modification purposes.

== The Document Object Model ==

The Document Object Model is an API that allows for the interpretation of HTML and XML documents. It provides a structural representation of the document, which enables for easy modification and visual representation of the webpage. In essence, it connects the markup languages to structural code inside the browser. The DOM is contained in a tree structure that allows for easy search and retrieval of HTML and XML tags and their properties. This technology allows the Canvas tags to be read and retrieved in an efficient manner.

== Use of XML 3D ==

The Canvas 3D Tags will be based upon the syntax of its counterpart, the 2D Canvas tags. Essentially, the syntax will be similar to the following:<br/>

<pre>
<canvas>
 -- size is size of a size, orientation is a quaternion
 <cube position="x y z" orientation="a b c d" size="4"/>
 -- size is radius
 <sphere position="x y z" size="5"/>
</canvas>
</pre>

The Canvas Tags are already handled by the browser and therefore do not need to be implemented. Rather, the tags that will create the 3D objects will be added to the current Canvas Framework to enable the creation of 3D objects in memory. For example, the <cube /> tag will create a 3D cube in memory. The Attributes associated with it, such as position, orientation and size are all modifiers that will be exposed within JavaScript. Each tag that is used inside the Canvas Tag will have similar properties that will also be available for modification in the JavaScript Code. <br /><br />

Within a 3D world, a programmer can add numerous transformations sequentially in order to place an object in a given place. It will provide a larger flexibility aspect to the markup language:<br/>

<pre>
<canvas>
 -- either with an explicit matrix
 <transform position="m1..m16">
 <cube size="5"/>
 </transform>

 -- or with position and/or orientation
 <transform position="x y z" orientation="a b c d">
 <cube size="5"/>
 </transform>
</canvas>
</pre>

These are the basic principles that govern 3D controls over an Object. An object can be anything from a simple primitive such as a Cube or Sphere to a complex Mesh that can be downloaded from the internet or from the client's computer. Furthermore, the usage of lighting and camera modifications will follows the same structure as the primitives.

<pre>
<canvas>
 -- create a light
 <light type="spot" color="blue" position="x y z" orientation="a b c d" />
</canvas>
</pre>

== Use of XML 3D in JavaScript ==

In order to draw the objects onto the screen, JavaScript will be used to call functions inside the core of Firefox. The API will be written to allow programmers to not only access the various attributes of the Objects but also write drawing logic. The webpage will initiate a call to a JavaScript function that will start the drawing/manipulation code. This part of the project is being handled by Vlad Vukicevic from Mozilla. 

== Tag Reference ==

This is a list of Tags that will be Written as of Oct 1, 2006. This is a tentative List and will change in time:
* Primative Objects:
** [[Canvas_3D_-_Cube_Tag|<cube />]]
** [[Canvas_3D_-_Sphere_Tag|<sphere />]]
** [[Canvas_3D_-_Quad_Tag|<quad />]]
** [[Canvas_3D_-_Light_Tag|<light />]]
** [[Canvas_3D_-_Texture_Tag|<texture />]]
* Complex Objects:
** [[Canvas_3D_-_Mesh_Tag|<mesh />]]
* Group Modifiers:
** [[Canvas_3D_-_Transform_Tags|<transform>]]
** [[Canvas_3D_-_Scale_Tags|<scale>]]
** [[Canvas_3D_-_Rotate_Tags|<rotate>]]

== XML 3D Progress ==

There are several steps to starting this project which are beyond the scope of data modelling and design. Here is a list of steps that we used to setup our environment in order to start working on the Code.

# Experiences with the 1.8.0 Branch and [[Building_Firefox_1.5|How we Built Firefox 1.5]].
# Experiences with [[Debug_Mode_Firefox_1.5|Running Firefox In Debug Mode]].
# The place our code will sit is located in a stand-alone JavaScript file which webpages will inherit. The DOM will be used extensively in our code.
# A JavaScript file was created to read the tags from the HTML file dynamically.
# JSUnit tests were created to assure code quality.

== Iteration ==
*Iteration 1: Fix Tag Compatibility
**Restructure the parsing Code to Accept Tags without an Ending Tag
**Write a Test for the above task
**Rewrite Tag parsing Code
**Write Test for the Tag Parsing Code
**Update the Wiki with new content

*Iteration 2: Create New 2D Tags
**Line Tag
***Create <Line> Tag
***Write Test for the Line Tag
**Arc Tag
***Create <Arc> Tag
***Write Test for the Arc Tag
**Circle Tag
***Create <Circle> Tag
***Write Test for the Circle Tag
**Rectangle Tag
***Create <Rectangle> Tag
***Write Test for the Rectangle Tag
**Image Tag
***Create <Image> Tag
***Write Test for the Image Tag
**Update Wiki Site to reflect Above Changes

== References Used ==

[http://wiki.mozilla.org/Main_Page Mozilla Wiki Main Page]<br />
[http://wiki.mozilla.org/Canvas:3D Official Canvas 3D Wiki]<br />
[http://whatwg.org/specs/web-apps/current-work/#scs-dynamic Canvas 2D Reference]<br />
[http://whatwg.org/specs/web-apps/current-work/#the-3d Canvas 3D Reference]