Skip to content

Commit aa8d7c2

Browse files
committed
Adds jsdoc for new Material methods in async refactor
1 parent ecff7ce commit aa8d7c2

File tree

1 file changed

+45
-0
lines changed

1 file changed

+45
-0
lines changed

packages/engine/Source/Scene/Material.js

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,7 +393,28 @@ Material.fromType = function (type, uniforms) {
393393
return material;
394394
};
395395

396+
/**
397+
* Creates a new material using an existing material type and returns a promise that resolves when
398+
* all of the material's resources have been loaded.
399+
*
400+
* @param {string} type The base material type.
401+
* @param {object} [uniforms] Overrides for the default uniforms.
402+
* @returns {Promise<Material>} A promise that resolves to a new material object when all resources are loaded.
403+
*
404+
* @exception {DeveloperError} material with that type does not exist.
405+
*
406+
* @example
407+
* const material = await Cesium.Material.fromTypeAsync('Image', {
408+
* image: '../Images/Cesium_Logo_overlay.png'
409+
* });
410+
*/
396411
Material.fromTypeAsync = async function (type, uniforms) {
412+
//>>includeStart('debug', pragmas.debug);
413+
if (!defined(Material._materialCache.getMaterial(type))) {
414+
throw new DeveloperError(`material with type '${type}' does not exist.`);
415+
}
416+
//>>includeEnd('debug');
417+
397418
const initializationPromises = [];
398419
// Unlike Material.fromType, we need to specify the uniforms in the Material constructor up front,
399420
// or else anything that needs to be async loaded won't be kicked off until the next Update call.
@@ -411,6 +432,13 @@ Material.fromTypeAsync = async function (type, uniforms) {
411432
return material;
412433
};
413434

435+
/**
436+
* Recursively traverses the material and its submaterials to collect all initialization promises.
437+
* @param {Material} material The material to traverse.
438+
* @param {Promise[]} initializationPromises The array to collect promises into.
439+
*
440+
* @private
441+
*/
414442
function getInitializationPromises(material, initializationPromises) {
415443
initializationPromises.push(material._initializationPromises);
416444
const submaterials = material.materials;
@@ -936,6 +964,16 @@ function createTexture2DUpdateFunction(uniformId) {
936964
};
937965
}
938966

967+
/**
968+
* For a given uniform ID, potentially loads a texture image for the material, if the uniform value is a Resource or string URL,
969+
* and has changed since the last time this was called (either on construction or update).
970+
*
971+
* @param {Material} material The material to load the texture for.
972+
* @param {string} uniformId The ID of the uniform of the image.
973+
* @returns {Promise} A promise that resolves when the image is loaded, or a resolved promise if image loading is not necessary.
974+
*
975+
* @private
976+
*/
939977
function loadTexture2DImageForUniform(material, uniformId) {
940978
const uniforms = material.uniforms;
941979
const uniformValue = uniforms[uniformId];
@@ -1010,6 +1048,13 @@ function createCubeMapUpdateFunction(uniformId) {
10101048
};
10111049
}
10121050

1051+
/**
1052+
* Loads the images for a cubemap uniform, if it has changed since the last time this was called.
1053+
*
1054+
* @param {Material} material The material to load the cubemap images for.
1055+
* @param {string} uniformId The ID of the uniform that corresponds to the cubemap images.
1056+
* @returns {Promise} A promise that resolves when the images are loaded, or a resolved promise if image loading is not necessary.
1057+
*/
10131058
async function loadCubeMapImagesForUniform(material, uniformId) {
10141059
const uniforms = material.uniforms;
10151060
const uniformValue = uniforms[uniformId];

0 commit comments

Comments
 (0)