WebGL Textures: Introduction to Mipmaps, Sub Images & Atlases (2015)
Initialization Activity Diagram
This section provides an overview of functionality implemented within the files GLControl.js and GLEntity.js. The files initialize WebGL properties for each of the book's example projects. The first book WebGL Textures & Vertices: Beginner's Guide covers GLControl.js and GLEntity.js in detail. However every book in the Online 3D Media with WebGL series, concludes with an outline for the supporting files. Those new to WebGL, might want to study the code and comments in detail or read the first book.
The JavaScript file GLControl.js declares the GLControl prototype class. GLControl prepares the WebGL context, program, shaders, and buffers. GLControl maintains an array of GLEntity. The controller calls initialization methods for each GLEntity in the array. The GLEntity prototype class initializes textures. Projects may initialize multiple textures for a set of GLEntity, or multiple GLEntity with one texture.
The following chart demonstrates the initialization process which applies to every project in the book. The solid black circle at the top of the diagram indicates the start of initialization. Each example creates a reference to GLControl(). Parameters passed to the GLControl constructor include a Uint16Array of indices, a Float32Array of vertices with texels, and an array of GLEntity. Each project is defined within it's own prototype class. Pass a reference to the project's class as the last parameter to GLControl().
Functions declared within the JavaScript file GLEntity.js appear in rectangular boxes with light blue backgrounds. For those with black and white displays, GLEntity methods display with light gray backgrounds. The methods with white backgrounds, are defined within the controller GLControl.
The solid black circle with a black outline indicates the end of the initialization process. Method animOne() activates last. animOne() renders one frame of the project's scene.
Diagram 13: Initialization Activity Diagram
GLControl Constructor
The constructor for GLControl initializes everything needed for a WebGL program. Formal parameters in order include aVert, aIdx, aE, and glDemo. The aVert parameter by default includes a Float32Array of interleaved vertices and texels. The aIdx parameter is a Uint16Array for use as an element array buffer. The aE parameter is an array of GLEntity. The glDemo parameter references the current project. In other words glDemo is an instance of a classimplemented for one of the book's examples.
The constructor assigns the aE parameter to the aEntity property, saving the array of GLEntity. The constructor assigns the glDemo parameter to the glDemo property. Many methods need references to the current project.
GLControl Initialization
The constructor for GLControl calls the following methods in order getGLContext(), getProgram(), getBuffers(), getImages(), and last setListeners().
Method getGLContext() obtains and saves a WebGLContext reference, to the instance variable gl. Method getProgram() prepares the program from a fragment and vertex shader. If the Web page doesn't declare a shader, then getProgram() uses the provided default shaders. The compiled and linked program is saved to the instance variable program. Method getBuffers() prepares an element array buffer from the Uint16Array passed to the GLControlconstructor. Method getBuffers() prepares a vertex buffer object from the Float32Array passed to the GLControl constructor. Method getImages() calls the GLEntity method getImageVariables(), for each GLEntity maintained in the aEntity array. Method setListeners() assigns event listeners to buttons which play an animation, and stop the animation. Additionally setListeners() assigns a click event listener to the canvas, which renders one frame of the animation.
After all textures have loaded, setProgramVariables() calls method animOne() to display one frame of the scene.
See the GLControl source code.
GLEntity Constructor
The constructor for GLEntity initializes everything needed for a WebGLTexture and a matrix. The matrix allows display of each entity with transformation, such as position or rotation. In other words a GLEntity may represent individual mesh elements, with unique textures.
Formal constructor parameters in order, include s and i. The s parameter represents either a String path to an image file or null. Not every entity needs an image file. The i parameter is an integer. The constructor assigns the iparameter to the idx property. The constructor assigns the s parameter to the sSrc property. During initialization, method getImageVariables() loads an image file from the sSrc file path.
GLEntity Structure
The GLEntity class includes instance variables sSrc, img, texture, uSampler, aTexCoord, idx, and matrix.
The String variable named sSrc, contains the path to an image file if one exists. GLEntity applies data from an image file to a texture. However GLEntity may apply procedurally generated color data to a texture, as well. The imgvariable maintains either an Image object, Uint8Array of color data, or null. The texture variable maintains a WebGLTexture generated from data in the img variable, when available. By default the controller requires at least one GLEntity with a valid WebGLTexture. Additional entities with null textures may process matrices or other data. In other words every entity in the controller's list does not need a valid texture property.
The idx variable is an integer which uniquely represents one entity in the array of entities. The idx property has three uses. Associate GLEntity properties with a shader attribute, shader uniform, and a texture unit.
Use the idx property to associate a uniform with the GLEntity instance variable uSampler, and an attribute with the instance variable aTexCoord. The uSampler variable is the location of a uniform sampler2D from the fragment shader. The aTexCoord variable is the location of an attribute for processing texture coordinates, within the vertex shader. The idx property of a GLEntity reference works with the two shader variables. For example the GLEntity with an idxvalue of 0, references a sampler named u_sampler0 and an attribute named a_tex_coord0. The GLEntity with an idx value of 1, references a sampler named u_sampler1 and an attribute named a_tex_coord1. However, if shader variables beyond idx value 0 aren't available, then examples work fine without them.
The GLEntity idx property also refers to the associated texture unit. For example when idx equals 1, and the entity maintains a texture, then the texture unit equals TEXTURE1. The following listing activates a texture unit, based on the entity's idx value.
gl.activeTexture
(
gl.TEXTURE0 + entity.idx
);
Activate GLEntity Texture Unit
Use the idx property to associate the uSampler property with the entity's texture unit. The following listing assigns the entity's sampler to a texture unit with the WebGL method uniformi().
gl.uniform1i
(
entity.uSampler,
entity.idx
);
Listing 50: Assign GLEntity Sampler to Texture Unit
GLEntity Initialization
The controller calls GLEntity method getImageVariables(). Method getImageVariables() obtains variable locations from the shaders, and prepares to load any images. Method setImage() activates when images load asynchronously. However code may call method setImage() synchronously with procedurally generated color data. In that case, the texture initializes without waiting for a file download. Method setImage() completes texture initialization. After all textures have initialized, setImage() calls the controller method setProgramVariables() once.
It's necessary to call setProgramVariables() after textures have initialized. Method setProgramVariables() validates the program. Some browsers fail validation if shader variables associated with textures, haven't initialized.
See the GLEntity source code.
Initialization Activity Diagram Summary
This section provided an overview of functionality implemented within the files GLControl.js and GLEntity.js. The files initialize WebGL properties for each of the book's example projects. The first book WebGL Textures & Vertices: Beginner's Guide covers GLControl.js and GLEntity.js in detail. However every book in the Online 3D Media with WebGL series, concludes with an outline for the supporting files. Those new to WebGL, might want to study the code and comments in detail or read the first book.
The JavaScript file GLControl.js declares the GLControl prototype class. GLControl prepares the WebGL context, program, shaders, and buffers. GLControl maintains an array of GLEntity. The controller calls initialization methods for each GLEntity in the array. The GLEntity prototype class initializes textures. Projects may initialize multiple textures for a set of GLEntity, or multiple GLEntity with one texture.
Animation Activity Diagram
The following activity diagram provides an overview of the rendering sequence. The solid black circle represents the start of the animation sequence. The solid black circle with black outline represents the end of the animation sequence.
File GLControl.js defines every method displayed in the activity diagram. However if a project defines method render(), then the example project's implementation of render() displays frames of the animation. Otherwise if a project doesn't define method render(), then the default rendering method renderDefault() displays frames of the animation. We defined each project in it's own prototype class. Some projects define a render() method and others don't. The GLControl constructor assigns either the project's render() method or the GLControl renderDefault() method to the render property.
Tap the Play button to start the animation with method animStart(). Tap the canvas to see one frame of the animation with animOne(). The JavaScript method requestAnimationFrame() triggers the GLControl method drawScene(). Method drawScene() times a series of animation frames and calls the render() method. We use a timer named checkFrameTime() because some devices render too quickly. checkFrameTime() slows down rendering, based on the value assigned to property FRAME_INTERVAL. Method checkFrameTime() recursively calls drawScene() until sufficient time passes. To display a frame, the render() method executes. A frame counter terminates animation automatically with a call to animStop()
Diagram 14: Animation Activity Diagram
Animation Activity Diagram Summary