Uniform function templates

[lasalvavida]

As we continue adding pipeline stages, it is going to be important to keep a uniform template for pipeline stage functions so that they can be used in the same way.

I would propose the following:

/**
 * Performs some operation on a glTF hierarchy.
 *
 * @param {Object} gltf An object holding a glTF hierarchy.
 * @param {Object} [options] Defines more specific behavior for this stage.
 *
 * @returns {Promise} A promise that resolves when the stage completes.
 */
function stage(gltf, options) {
    ...
}

For #130:
I would classify the following as "stages" and should be converted to use this template. Anyone can feel free to do them in any order; it doesn't need to be one big pull request.

• addDefaults
• removeUnused (and all substages of removeUnused)
• mergeDuplicateVertices
• removeUnusedVertices
• mergeDuplicateAccessors
• removeDuplicatePrimitives
• convertDagToTree
• combineMeshes
• cacheOptimization
• quantizedAttributes
• encodeImages

[pjcozzi]

Agreed. I suggested this here: #75 (comment)

For an example in Cesium, see https://github.com/AnalyticalGraphicsInc/cesium/blob/3d-tiles/Source/Scene/Cesium3DTileContent.js

[JoshuaStorm]

I can start going through some of our unlabeled functions.

@lilleyse, thoughts on @lasalvavida's template before I move forward?

[lasalvavida]

@JoshuaStorm We probably want to go the whole way with @pjcozzi's suggestion. That is, make a Stage.js that looks something like this:

function Stage() {
    this.name = undefined;
    this.before = [];
    this.after = [];
};

Stage.prototype.run = function(gltf, options) {};

Then change the stages that currently just export functions to follow the Stage template.

module.exports = RemoveUnusedMeshesStage;

function RemoveUnusedMeshesStage() {
    this.name = 'removeUnusedMeshes';
    this.before = ['addPipelineExtras'];
    this.after = [];
}

RemoveUnusedMeshes.prototype.run = function(gltf, options) {
    return new Promise(resolve, reject) {
        // This is a synchronous stage, so it's pretty easy
        // async will need a little more work, but shouldn't be too difficult
        removeUnusedMeshes(gltf);
        resolve();
    }
}

The function bodies won't need to change until we have something set up for using the before and after to resolve dependencies, but it would be good to go ahead and set them up while we're making this change.

[lasalvavida]

We may also want to start keeping stages in a subdirectory of lib and utility functions in another.

[lilleyse]

Yup, all the suggestions here should be part of a larger cleanup/restructuring process, which I'm going to open an issue for pretty soon and @lasalvavida will handle.

@JoshuaStorm in the meantime there are a few other stages you can work on like pre-cache vertex optimization and transparent textures.

[JoshuaStorm]

@lasalvavida What exactly is the purpose of having a synchronous function return as a promise?

[lasalvavida]

@JoshuaStorm It is so that all stages can be executed in the same way. Eventually, when we have stage dependencies and custom pipelines we need to be able to run a stage by name without knowing anything about it and ideally without needing to do any special handling for async stages.

However, I think it actually makes more sense to have synchronous stages return undefined and asynchronous ones return promises which would be equally easy to handle, but would result in fewer changes to the code-base.