1.4 - File Organization For WebGL programs

As we discussed previously, a typical WebGL program is composed of the following types of files:

We need a file structure to help manage all of these files. But it is actually more complex than just managing a single WebGL program. A web site that contains WebGL computer graphics will possibly have multiple pages that contain graphics, and each web page might contain multiple WebGL programs that render into separate canvas areas. If all of your files are stored in a single folder on your server, you will have a very hard time managing those files as you perform upgrades and enhancements over time.

A basic principle of all file structures is to group related files into a separate folder. If you have multiple WebGL programs for a web site, some of the files will most likely be shared between programs. Therefore, a logical file organization would be to have a separate folder for each WebGL program that stores files unique to that program, and a common library folder for shared files.

File Organization Used for These Tutorials

The following file structure provides a basic organization for the files needed for a web site that implements multiple WebGL programs. The names of the folders are representative of what the folder holds. Note that:

  • All of the files that are unique to a WebGL program are saved in a unique folder for that program.
  • All of the files that are shared between WebGL programs are stored separately in a shared library folder called lib.
  • The “shared library” folder is organized by file type.

All of the examples in these tutorials use this file organization scheme which is shown in diagram format below.

../_images/file_structure.png


Web page file references use a standard notation for navigating a file hierarchy. The notation . means the current folder, which is the folder from which the current web page was loaded. The notation .. means the parent of the current folder. Therefore, when you see a file reference like this,

src="../../lib/learn_webgl.js"

this is a reference to a file that is accessed by going to the parent of the current folder, then its parent, then to the lib sub-folder, and then accessing the file learn_webgl.js. It is “best practice” to always include a file path for resource files, even if it is a default path. Therefore all files loaded from the current working folder are specified starting with ./ .

While this file structure is complex, it is better than no file structure at all. If a WebGL program is not working, the first thing you should check is whether all of the required files are being loaded properly. You can view errors related to missing files in the JavaScript console window. More details about the console window can be found in the debugging information in Section 2.

Glossary

folder hierarchy
an organization of file folders, where each folder has a unique parent folder and possibly contains one or more sub-folders
current working folder
the folder on the web server that contains the original HTML web page file.
relative file path
a series of folder references separated by forward slashes that starts from the current working folder.
absolute file path
a series of folder references starting the a single forward slash and separated by forward slashes. The path is always from the root folder of the web site on the web server.
.
a reference to the current working folder
..
a reference to the parent folder
Next Section - 1.5 - Software Organization For WebGL programs