Tutorials

These tutorials are targeted at people with a reasonable web programming knowledge (HTML and JavaScript languages) and a basic web 3D programming knowledge (WebGL API).

Tutorial 2 : Manage The Requests

This tutorial shows how SpiderGL manages the input asynchronous requests, introducing some example of different files loading, and the useful "aggregate request" too.

View DemoDownload Source

Many Computer Graphics algorithms make intensive use of multi-threading for asynchronous loading of data, with the goal of prioritizing request queues and avoid the application freezes while waiting for these data. Unfortunately, the JavaScript language does not officially support multi threaded execution. For this reason, SpiderGL provides some methods able to implement prioritized request queues. These functions are collected, together with those capable of performing synchronous loading, in the SpiderGL IO component.

The aim of this tutorial is to explore this component and to explain how SpiderGL manages the different kinds of requests.

To handle the streaming of various formats of data, the IO component is subdivided in classes, the main ones are:

  • TextRequest
  • JSONRequest
  • BinaryRequest
  • ImageRequest
  • XHRRequest
  • AggregateRequest

As you can easily imagine these sections corresponds to different types of files (respectively text, JSON, binary, image and XML), while the last one is a special section which contains methods that allow to package multiple requests together.

Once explained the IO component structure, you can move to the source code, to see some interesting examples of asynchronous request. As always, let us skip the (unchanged) HTML and JavaScript elements, and focus on the usual "tutorial" function where you can find several blocks of request, corresponding to different kind of data streaming.

Let's start with a plain text request. After a simple variable declaration to specify the URL path of the target file, the asynchronous request appears as: 

sglRequestText(textURL, {
  onSuccess: function (request) {
    log("TEXT ASYNCH");
    log("-> Request Elapsed Time : " + request.elapsedTime);
    log("-> Request Loaded Text : " + request.text);
  }
});

The IO method "requestText" performs an asynchronous text reading with callback, taking as input the file URL ("textURL") and few other options. In this example the function option, as the statement "onSuccess" suggests, sets the callback function to invoke when the request is fulfilled successfully. Note that upon success the text content loaded will be placed in the "text" attribute of the "request" parameter.

The next example block shows a JSON file request (JSON stands for JavaScript Object Notation, a text-based open standard designed for data interchange). After the usual variable setup of the URL path of the target file, the JSON file request is simply: 

sglRequestJSON(jsonURL, {
  onSuccess: function (request) {
    log("JSON ASYNCH");
    log("-> Request Elapsed Time : " + request.elapsedTime);
    var obj = request.json;
    for (var p in obj) {
      log("-> Request Loaded obj." + p + " : " + obj[p]);
    }
    log("");
  }
});

As in the previous example, the method "requestJSON" performs an asynchronous reading of the file placed at the input URL ("jsonURL") calling the specified callback. In case of success, the JSON-parsed object will be placed in the "json" attribute of the "request" parameter.

We conclude the asynchronous single requests presented in these examples with a last one introducing a binary file request. Next the customary URL path specification, the needed source code to load the selected binary file is this: 

sglRequestBinary(binaryURL, {
  onSuccess: function (request) {
    var bin = request.buffer;
    log("BINARY ASYNCH");
    log("-> Request Elapsed Time : " + request.elapsedTime);
    log("-> Request Loaded Bytes : " + bin.byteLength + "\n");
  }
});

Here again, as in the others two above shown requests, the method "requestBinary" performs an asynchronous loading of the file at the input URL ("binaryURL") and then call the appropriate callback. If the request successful, the read data bytes will be positioned in the "buffer" attribute of the "request" parameter.

The other methods for the asynchronous loading of the other file formats (image and XML) are analogues of the ones seen for text and JSON files, so we skip their description. Instead, we focus now on how the aggregate requests work. The corresponding method is designed to group multiple requests together, and to invoke the callback only when all of them have completed. First you need to create a JavaScript array where to push the different SpiderGL requests with the appropriate flag "send" set to false: 

var reqs = [];

reqs.push(new SglTextRequest(textURL, {
  send: false
}));
reqs.push(new SglJSONRequest(jsonURL, {
  send: false
}));
reqs.push(new SglBinaryRequest(binaryURL, {
  send: false	
}));

The next step is to perform the aggregate request. This is similar to the others requests just seen, except that this time we need to pass the requests array ("reqs") to the option field named "requests". In order to avoid confusion, we name the parameter of the "onSuccess" callback "req". 

var allReq = new SglAggregateRequest({
  requests: reqs,
  
  onSuccess: function (req) {
    log("AGGREGATE REQUEST");
    log("-> Request Elapsed Time : " + req.elapsedTime);
    var r = req.requests;
    for (var i = 0; i < r.length; i++) {
      if (i == 0) log("-> TEXT asynch request processed");
      if (i == 1) log("-> JSON asynch request processed");
      if (i == 2) log("-> BINARY asynch request processed");	
    }
  }
});

Before concluding this tutorial we underline that for the aggregate requests, like for the others asynchronous requests previously shown, the "onSuccess" callback is only one of the five possible events managed by SpiderGL.
The complete list is:

OnProgress-callback called when the request is in progress;
OnCancel-callback called when the request is aborted;
OnError-callback called when the request ended with failure;
OnFinish-callback called when the request ended;
OnSuccess-callback called when the request ended with success.

That is all for this tutorial, now it would be clear in what way SpiderGL allows you to manage the asynchronous and the aggregate requests for different type of data files.

In the next tutorial we will see how to interaction with the HTML5 canvas element using SpiderGL.

Tutorials List