diff --git a/packages/core/src/settings.js b/packages/core/src/settings.js index 7690b59..aec48dc 100644 --- a/packages/core/src/settings.js +++ b/packages/core/src/settings.js @@ -20,4 +20,22 @@ */ settings.PREFER_ENV = isMobile.any ? ENV.WEBGL : ENV.WEBGL2; +/** + * If set to `true`, Textures and BaseTexture objects stored + * in the caches ({@link PIXI.utils.TextureCache TextureCache} and + * {@link PIXI.utils.BaseTextureCache BaseTextureCache}) can *only* be + * used when calling {@link PIXI.Texture.from Texture.from} or + * {@link PIXI.BaseTexture.from BaseTexture.from}. + * Otherwise, these `from` calls throw an exception. Using this property + * can be useful if you want to enforce preloading all assets with + * {@link PIXI.Loader Loader}. + * + * @static + * @name STRICT_TEXTURE_CACHE + * @memberof PIXI.settings + * @type {boolean} + * @default false + */ +settings.STRICT_TEXTURE_CACHE = false; + export { settings }; diff --git a/packages/core/src/settings.js b/packages/core/src/settings.js index 7690b59..aec48dc 100644 --- a/packages/core/src/settings.js +++ b/packages/core/src/settings.js @@ -20,4 +20,22 @@ */ settings.PREFER_ENV = isMobile.any ? ENV.WEBGL : ENV.WEBGL2; +/** + * If set to `true`, Textures and BaseTexture objects stored + * in the caches ({@link PIXI.utils.TextureCache TextureCache} and + * {@link PIXI.utils.BaseTextureCache BaseTextureCache}) can *only* be + * used when calling {@link PIXI.Texture.from Texture.from} or + * {@link PIXI.BaseTexture.from BaseTexture.from}. + * Otherwise, these `from` calls throw an exception. Using this property + * can be useful if you want to enforce preloading all assets with + * {@link PIXI.Loader Loader}. + * + * @static + * @name STRICT_TEXTURE_CACHE + * @memberof PIXI.settings + * @type {boolean} + * @default false + */ +settings.STRICT_TEXTURE_CACHE = false; + export { settings }; diff --git a/packages/core/src/textures/BaseTexture.js b/packages/core/src/textures/BaseTexture.js index f3fa6a1..8c75be5 100644 --- a/packages/core/src/textures/BaseTexture.js +++ b/packages/core/src/textures/BaseTexture.js @@ -533,13 +533,15 @@ * @param {string|HTMLImageElement|HTMLCanvasElement|SVGElement|HTMLVideoElement} source - The * source to create base texture from. * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @returns {PIXI.BaseTexture} The new base texture. */ - static from(source, options) + static from(source, options, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -555,6 +557,12 @@ let baseTexture = BaseTextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !baseTexture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in BaseTextureCache.`); + } + if (!baseTexture) { baseTexture = new BaseTexture(source, options); diff --git a/packages/core/src/settings.js b/packages/core/src/settings.js index 7690b59..aec48dc 100644 --- a/packages/core/src/settings.js +++ b/packages/core/src/settings.js @@ -20,4 +20,22 @@ */ settings.PREFER_ENV = isMobile.any ? ENV.WEBGL : ENV.WEBGL2; +/** + * If set to `true`, Textures and BaseTexture objects stored + * in the caches ({@link PIXI.utils.TextureCache TextureCache} and + * {@link PIXI.utils.BaseTextureCache BaseTextureCache}) can *only* be + * used when calling {@link PIXI.Texture.from Texture.from} or + * {@link PIXI.BaseTexture.from BaseTexture.from}. + * Otherwise, these `from` calls throw an exception. Using this property + * can be useful if you want to enforce preloading all assets with + * {@link PIXI.Loader Loader}. + * + * @static + * @name STRICT_TEXTURE_CACHE + * @memberof PIXI.settings + * @type {boolean} + * @default false + */ +settings.STRICT_TEXTURE_CACHE = false; + export { settings }; diff --git a/packages/core/src/textures/BaseTexture.js b/packages/core/src/textures/BaseTexture.js index f3fa6a1..8c75be5 100644 --- a/packages/core/src/textures/BaseTexture.js +++ b/packages/core/src/textures/BaseTexture.js @@ -533,13 +533,15 @@ * @param {string|HTMLImageElement|HTMLCanvasElement|SVGElement|HTMLVideoElement} source - The * source to create base texture from. * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @returns {PIXI.BaseTexture} The new base texture. */ - static from(source, options) + static from(source, options, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -555,6 +557,12 @@ let baseTexture = BaseTextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !baseTexture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in BaseTextureCache.`); + } + if (!baseTexture) { baseTexture = new BaseTexture(source, options); diff --git a/packages/core/src/textures/Texture.js b/packages/core/src/textures/Texture.js index ec845e1..d9b4adf 100644 --- a/packages/core/src/textures/Texture.js +++ b/packages/core/src/textures/Texture.js @@ -321,16 +321,18 @@ * The source can be - frame id, image url, video url, canvas element, video element, base texture * * @static - * @param {number|string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source + * @param {string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source * Source to create texture from * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @return {PIXI.Texture} The newly created texture */ - static from(source, options = {}) + static from(source, options = {}, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -346,6 +348,12 @@ let texture = TextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !texture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in TextureCache.`); + } + if (!texture) { if (!options.resolution) diff --git a/packages/core/src/settings.js b/packages/core/src/settings.js index 7690b59..aec48dc 100644 --- a/packages/core/src/settings.js +++ b/packages/core/src/settings.js @@ -20,4 +20,22 @@ */ settings.PREFER_ENV = isMobile.any ? ENV.WEBGL : ENV.WEBGL2; +/** + * If set to `true`, Textures and BaseTexture objects stored + * in the caches ({@link PIXI.utils.TextureCache TextureCache} and + * {@link PIXI.utils.BaseTextureCache BaseTextureCache}) can *only* be + * used when calling {@link PIXI.Texture.from Texture.from} or + * {@link PIXI.BaseTexture.from BaseTexture.from}. + * Otherwise, these `from` calls throw an exception. Using this property + * can be useful if you want to enforce preloading all assets with + * {@link PIXI.Loader Loader}. + * + * @static + * @name STRICT_TEXTURE_CACHE + * @memberof PIXI.settings + * @type {boolean} + * @default false + */ +settings.STRICT_TEXTURE_CACHE = false; + export { settings }; diff --git a/packages/core/src/textures/BaseTexture.js b/packages/core/src/textures/BaseTexture.js index f3fa6a1..8c75be5 100644 --- a/packages/core/src/textures/BaseTexture.js +++ b/packages/core/src/textures/BaseTexture.js @@ -533,13 +533,15 @@ * @param {string|HTMLImageElement|HTMLCanvasElement|SVGElement|HTMLVideoElement} source - The * source to create base texture from. * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @returns {PIXI.BaseTexture} The new base texture. */ - static from(source, options) + static from(source, options, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -555,6 +557,12 @@ let baseTexture = BaseTextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !baseTexture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in BaseTextureCache.`); + } + if (!baseTexture) { baseTexture = new BaseTexture(source, options); diff --git a/packages/core/src/textures/Texture.js b/packages/core/src/textures/Texture.js index ec845e1..d9b4adf 100644 --- a/packages/core/src/textures/Texture.js +++ b/packages/core/src/textures/Texture.js @@ -321,16 +321,18 @@ * The source can be - frame id, image url, video url, canvas element, video element, base texture * * @static - * @param {number|string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source + * @param {string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source * Source to create texture from * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @return {PIXI.Texture} The newly created texture */ - static from(source, options = {}) + static from(source, options = {}, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -346,6 +348,12 @@ let texture = TextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !texture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in TextureCache.`); + } + if (!texture) { if (!options.resolution) diff --git a/packages/core/test/BaseTexture.js b/packages/core/test/BaseTexture.js index 635173a..a4b8bf1 100644 --- a/packages/core/test/BaseTexture.js +++ b/packages/core/test/BaseTexture.js @@ -1,5 +1,6 @@ const { BaseTextureCache, TextureCache } = require('@pixi/utils'); const { BaseTexture, Texture, RenderTexture, resources } = require('../'); +const { settings } = require('@pixi/settings'); const { ImageResource, SVGResource, VideoResource } = resources; const URL = 'foo.png'; @@ -234,4 +235,14 @@ expect(texture.baseTexture.realWidth).to.equal(15); expect(texture.baseTexture.realHeight).to.equal(15); }); + + it('should throw and error in strict from mode', function () + { + const id = 'baz'; + + expect(() => BaseTexture.from(id, {}, true)).to.throw(`The cacheId "${id}" does not exist in BaseTextureCache.`); + settings.STRICT_TEXTURE_CACHE = true; + expect(() => BaseTexture.from(id)).to.throw(`The cacheId "${id}" does not exist in BaseTextureCache.`); + settings.STRICT_TEXTURE_CACHE = false; + }); }); diff --git a/packages/core/src/settings.js b/packages/core/src/settings.js index 7690b59..aec48dc 100644 --- a/packages/core/src/settings.js +++ b/packages/core/src/settings.js @@ -20,4 +20,22 @@ */ settings.PREFER_ENV = isMobile.any ? ENV.WEBGL : ENV.WEBGL2; +/** + * If set to `true`, Textures and BaseTexture objects stored + * in the caches ({@link PIXI.utils.TextureCache TextureCache} and + * {@link PIXI.utils.BaseTextureCache BaseTextureCache}) can *only* be + * used when calling {@link PIXI.Texture.from Texture.from} or + * {@link PIXI.BaseTexture.from BaseTexture.from}. + * Otherwise, these `from` calls throw an exception. Using this property + * can be useful if you want to enforce preloading all assets with + * {@link PIXI.Loader Loader}. + * + * @static + * @name STRICT_TEXTURE_CACHE + * @memberof PIXI.settings + * @type {boolean} + * @default false + */ +settings.STRICT_TEXTURE_CACHE = false; + export { settings }; diff --git a/packages/core/src/textures/BaseTexture.js b/packages/core/src/textures/BaseTexture.js index f3fa6a1..8c75be5 100644 --- a/packages/core/src/textures/BaseTexture.js +++ b/packages/core/src/textures/BaseTexture.js @@ -533,13 +533,15 @@ * @param {string|HTMLImageElement|HTMLCanvasElement|SVGElement|HTMLVideoElement} source - The * source to create base texture from. * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @returns {PIXI.BaseTexture} The new base texture. */ - static from(source, options) + static from(source, options, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -555,6 +557,12 @@ let baseTexture = BaseTextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !baseTexture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in BaseTextureCache.`); + } + if (!baseTexture) { baseTexture = new BaseTexture(source, options); diff --git a/packages/core/src/textures/Texture.js b/packages/core/src/textures/Texture.js index ec845e1..d9b4adf 100644 --- a/packages/core/src/textures/Texture.js +++ b/packages/core/src/textures/Texture.js @@ -321,16 +321,18 @@ * The source can be - frame id, image url, video url, canvas element, video element, base texture * * @static - * @param {number|string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source + * @param {string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source * Source to create texture from * @param {object} [options] See {@link PIXI.BaseTexture}'s constructor for options. + * @param {boolean} [strict] Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @return {PIXI.Texture} The newly created texture */ - static from(source, options = {}) + static from(source, options = {}, strict = settings.STRICT_TEXTURE_CACHE) { + const isFrame = typeof source === 'string'; let cacheId = null; - if (typeof source === 'string') + if (isFrame) { cacheId = source; } @@ -346,6 +348,12 @@ let texture = TextureCache[cacheId]; + // Strict-mode rejects invalid cacheIds + if (isFrame && strict && !texture) + { + throw new Error(`The cacheId "${cacheId}" does not exist in TextureCache.`); + } + if (!texture) { if (!options.resolution) diff --git a/packages/core/test/BaseTexture.js b/packages/core/test/BaseTexture.js index 635173a..a4b8bf1 100644 --- a/packages/core/test/BaseTexture.js +++ b/packages/core/test/BaseTexture.js @@ -1,5 +1,6 @@ const { BaseTextureCache, TextureCache } = require('@pixi/utils'); const { BaseTexture, Texture, RenderTexture, resources } = require('../'); +const { settings } = require('@pixi/settings'); const { ImageResource, SVGResource, VideoResource } = resources; const URL = 'foo.png'; @@ -234,4 +235,14 @@ expect(texture.baseTexture.realWidth).to.equal(15); expect(texture.baseTexture.realHeight).to.equal(15); }); + + it('should throw and error in strict from mode', function () + { + const id = 'baz'; + + expect(() => BaseTexture.from(id, {}, true)).to.throw(`The cacheId "${id}" does not exist in BaseTextureCache.`); + settings.STRICT_TEXTURE_CACHE = true; + expect(() => BaseTexture.from(id)).to.throw(`The cacheId "${id}" does not exist in BaseTextureCache.`); + settings.STRICT_TEXTURE_CACHE = false; + }); }); diff --git a/packages/core/test/Texture.js b/packages/core/test/Texture.js index 3ccdf1c..9011454 100644 --- a/packages/core/test/Texture.js +++ b/packages/core/test/Texture.js @@ -1,6 +1,7 @@ const { BaseTextureCache, TextureCache } = require('@pixi/utils'); const { Rectangle, Point } = require('@pixi/math'); const { BaseTexture, Texture } = require('../'); +const { settings } = require('@pixi/settings'); const URL = 'foo.png'; const NAME = 'foo'; @@ -205,4 +206,14 @@ expect(texture.height).to.equal(20); texture.destroy(true); }); + + it('should throw and error in strict from mode', function () + { + const id = 'baz'; + + expect(() => Texture.from(id, {}, true)).to.throw(`The cacheId "${id}" does not exist in TextureCache.`); + settings.STRICT_TEXTURE_CACHE = true; + expect(() => Texture.from(id)).to.throw(`The cacheId "${id}" does not exist in TextureCache.`); + settings.STRICT_TEXTURE_CACHE = false; + }); });