pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 9.71 kB

Source Map (JSON)

View Raw

{"version":3,"file":"RenderableGCSystem.mjs","sources":["../../../../../src/rendering/renderers/shared/texture/RenderableGCSystem.ts"],"sourcesContent":["import { ExtensionType } from '../../../../extensions/Extensions';\nimport { deprecation } from '../../../../utils/logging/deprecation';\n\nimport type { Renderer } from '../../types';\nimport type { Renderable } from '../Renderable';\nimport type { System } from '../system/System';\n\n/**\n * Options for the {@link RenderableGCSystem}.\n * @category rendering\n * @property {boolean} [renderableGCActive=true] - If set to true, this will enable the garbage collector on the renderables.\n * @property {number} [renderableGCAMaxIdle=60000] -\n * The maximum idle frames before a texture is destroyed by garbage collection.\n * @property {number} [renderableGCCheckCountMax=60000] - time between two garbage collections.\n * @advanced\n * @deprecated since 8.15.0\n */\nexport interface RenderableGCSystemOptions\n{\n /**\n * If set to true, this will enable the garbage collector on the GPU.\n * @default true\n */\n renderableGCActive: boolean;\n /**\n * The maximum idle frames before a texture is destroyed by garbage collection.\n * @default 60 * 60\n */\n renderableGCMaxUnusedTime: number;\n /**\n * Frames between two garbage collections.\n * @default 600\n */\n renderableGCFrequency: number;\n}\n\n/**\n * The RenderableGCSystem is responsible for cleaning up GPU resources that are no longer being used.\n *\n * When rendering objects like sprites, text, etc - GPU resources are created and managed by the renderer.\n * If these objects are no longer needed but not properly destroyed (via sprite.destroy()), their GPU resources\n * would normally leak. This system prevents that by automatically cleaning up unused GPU resources.\n *\n * Key features:\n * - Runs every 30 seconds by default to check for unused resources\n * - Cleans up resources not rendered for over 1 minute\n * - Works independently of rendering - will clean up even when not actively rendering\n * - When cleaned up resources are needed again, new GPU objects are quickly assigned from a pool\n * - Can be disabled with renderableGCActive:false for manual control\n *\n * Best practices:\n * - Always call destroy() explicitly when done with renderables (e.g. sprite.destroy())\n * - This system is a safety net, not a replacement for proper cleanup\n * - Adjust frequency and timeouts via options if needed\n * @example\n * ```js\n * // Sprite created but reference lost without destroy\n * let sprite = new Sprite(texture);\n *\n * // internally the renderer will assign a resource to the sprite\n * renderer.render(sprite);\n *\n * sprite = null; // Reference lost but GPU resources still exist\n *\n * // After 1 minute of not being rendered:\n * // - RenderableGC will clean up the sprite's GPU resources\n * // - JS garbage collector can then clean up the sprite itself\n * ```\n * @category rendering\n * @advanced\n * @deprecated since 8.15.0\n */\nexport class RenderableGCSystem implements System<RenderableGCSystemOptions>\n{\n /**\n * Extension metadata for registering this system with the renderer.\n * @ignore\n */\n public static extension = {\n type: [\n ExtensionType.WebGLSystem,\n ExtensionType.WebGPUSystem,\n ExtensionType.CanvasSystem,\n ],\n name: 'renderableGC',\n priority: 0\n } as const;\n\n /**\n * Default configuration options for the garbage collection system.\n * These can be overridden when initializing the renderer.\n * @deprecated since 8.15.0\n */\n public static defaultOptions: RenderableGCSystemOptions = {\n /** Enable/disable the garbage collector */\n renderableGCActive: true,\n /** Time in ms before an unused resource is collected (default 1 minute) */\n renderableGCMaxUnusedTime: 60000,\n /** How often to run garbage collection in ms (default 30 seconds) */\n renderableGCFrequency: 30000,\n };\n\n /** Maximum time in ms a resource can be unused before being garbage collected */\n public maxUnusedTime: number;\n\n /** Reference to the renderer this system belongs to */\n private _renderer: Renderer;\n\n /**\n * Creates a new RenderableGCSystem instance.\n * @param renderer - The renderer this garbage collection system works for\n */\n constructor(renderer: Renderer)\n {\n this._renderer = renderer;\n }\n\n /**\n * Initializes the garbage collection system with the provided options.\n * @param options - Configuration options for the renderer\n */\n public init(options: RenderableGCSystemOptions): void\n {\n options = { ...RenderableGCSystem.defaultOptions, ...options };\n\n this.maxUnusedTime = options.renderableGCMaxUnusedTime;\n }\n\n /**\n * Gets whether the garbage collection system is currently enabled.\n * @returns True if GC is enabled, false otherwise\n */\n get enabled(): boolean\n {\n // #if _DEBUG\n deprecation('8.15.0', 'RenderableGCSystem.enabled is deprecated, please use the GCSystem.enabled instead.');\n // #endif\n\n return this._renderer.gc.enabled;\n }\n\n /**\n * Enables or disables the garbage collection system.\n * When enabled, schedules periodic cleanup of resources.\n * When disabled, cancels all scheduled cleanups.\n */\n set enabled(value: boolean)\n {\n // #if _DEBUG\n deprecation('8.15.0', 'RenderableGCSystem.enabled is deprecated, please use the GCSystem.enabled instead.');\n // #endif\n this._renderer.gc.enabled = value;\n }\n\n /**\n * Adds a hash table to be managed by the garbage collector.\n * @param context - The object containing the hash table\n * @param hash - The property name of the hash table\n */\n public addManagedHash<T>(context: T, hash: string): void\n {\n // #if _DEBUG\n // eslint-disable-next-line max-len\n deprecation('8.15.0', 'RenderableGCSystem.addManagedHash is deprecated, please use the GCSystem.addCollection instead.');\n // #endif\n this._renderer.gc.addCollection(context, hash, 'hash');\n }\n\n /**\n * Adds an array to be managed by the garbage collector.\n * @param context - The object containing the array\n * @param hash - The property name of the array\n */\n public addManagedArray<T>(context: T, hash: string): void\n {\n // #if _DEBUG\n // eslint-disable-next-line max-len\n deprecation('8.15.0', 'RenderableGCSystem.addManagedArray is deprecated, please use the GCSystem.addCollection instead.');\n // #endif\n this._renderer.gc.addCollection(context, hash, 'array');\n }\n\n /**\n * Starts tracking a renderable for garbage collection.\n * @param _renderable - The renderable to track\n * @deprecated since 8.15.0\n */\n public addRenderable(_renderable: Renderable): void\n {\n // #if _DEBUG\n deprecation('8.15.0', 'RenderableGCSystem.addRenderable is deprecated, please use the GCSystem instead.');\n // #endif\n this._renderer.gc.addResource(_renderable, 'renderable');\n }\n\n /**\n * Performs garbage collection by cleaning up unused renderables.\n * Removes renderables that haven't been used for longer than maxUnusedTime.\n */\n public run(): void\n {\n // #if _DEBUG\n deprecation('8.15.0', 'RenderableGCSystem.run is deprecated, please use the GCSystem instead.');\n // #endif\n this._renderer.gc.run();\n }\n\n /** Cleans up the garbage collection system. Disables GC and removes all tracked resources. */\n public destroy(): void\n {\n this._renderer = null as any as Renderer;\n }\n}\n"],"names":[],"mappings":";;;;AAwEO,MAAM,mBAAA,GAAN,MAAM,mBAAA,CACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAuCI,YAAY,QAAA,EACZ;AACI,IAAA,IAAA,CAAK,SAAA,GAAY,QAAA;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,KAAK,OAAA,EACZ;AACI,IAAA,OAAA,GAAU,EAAE,GAAG,mBAAA,CAAmB,cAAA,EAAgB,GAAG,OAAA,EAAQ;AAE7D,IAAA,IAAA,CAAK,gBAAgB,OAAA,CAAQ,yBAAA;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,OAAA,GACJ;AAEI,IAAA,WAAA,CAAY,UAAU,oFAAoF,CAAA;AAG1G,IAAA,OAAO,IAAA,CAAK,UAAU,EAAA,CAAG,OAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,QAAQ,KAAA,EACZ;AAEI,IAAA,WAAA,CAAY,UAAU,oFAAoF,CAAA;AAE1G,IAAA,IAAA,CAAK,SAAA,CAAU,GAAG,OAAA,GAAU,KAAA;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,cAAA,CAAkB,SAAY,IAAA,EACrC;AAGI,IAAA,WAAA,CAAY,UAAU,iGAAiG,CAAA;AAEvH,IAAA,IAAA,CAAK,SAAA,CAAU,EAAA,CAAG,aAAA,CAAc,OAAA,EAAS,MAAM,MAAM,CAAA;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,eAAA,CAAmB,SAAY,IAAA,EACtC;AAGI,IAAA,WAAA,CAAY,UAAU,kGAAkG,CAAA;AAExH,IAAA,IAAA,CAAK,SAAA,CAAU,EAAA,CAAG,aAAA,CAAc,OAAA,EAAS,MAAM,OAAO,CAAA;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,cAAc,WAAA,EACrB;AAEI,IAAA,WAAA,CAAY,UAAU,kFAAkF,CAAA;AAExG,IAAA,IAAA,CAAK,SAAA,CAAU,EAAA,CAAG,WAAA,CAAY,WAAA,EAAa,YAAY,CAAA;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,GAAA,GACP;AAEI,IAAA,WAAA,CAAY,UAAU,wEAAwE,CAAA;AAE9F,IAAA,IAAA,CAAK,SAAA,CAAU,GAAG,GAAA,EAAI;AAAA,EAC1B;AAAA;AAAA,EAGO,OAAA,GACP;AACI,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AAAA,EACrB;AACJ,CAAA;AAAA;AAAA;AAAA;AAAA;AA5Ia,mBAAA,CAMK,SAAA,GAAY;AAAA,EACtB,IAAA,EAAM;AAAA,IACF,aAAA,CAAc,WAAA;AAAA,IACd,aAAA,CAAc,YAAA;AAAA,IACd,aAAA,CAAc;AAAA,GAClB;AAAA,EACA,IAAA,EAAM,cAAA;AAAA,EACN,QAAA,EAAU;AACd,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAdS,mBAAA,CAqBK,cAAA,GAA4C;AAAA;AAAA,EAEtD,kBAAA,EAAoB,IAAA;AAAA;AAAA,EAEpB,yBAAA,EAA2B,GAAA;AAAA;AAAA,EAE3B,qBAAA,EAAuB;AAC3B,CAAA;AA5BG,IAAM,kBAAA,GAAN;;;;"}