pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 6.02 kB

Source Map (JSON)

View Raw

{"version":3,"file":"CullerPlugin.mjs","sources":["../../src/culling/CullerPlugin.ts"],"sourcesContent":["import { ExtensionType } from '../extensions/Extensions';\nimport { Culler } from './Culler';\n\nimport type { ExtensionMetadata } from '../extensions/Extensions';\nimport type { Renderer } from '../rendering/renderers/types';\nimport type { Container } from '../scene/container/Container';\n\n/**\n * Application options for the {@link CullerPlugin}.\n * These options control how your application handles culling of display objects.\n * @example\n * ```ts\n * import { Application } from 'pixi.js';\n *\n * // Create application\n * const app = new Application();\n * await app.init({\n * culler: {\n * updateTransform: false // Skip updating transforms for culled objects\n * }\n * });\n * ```\n * @category app\n * @standard\n */\nexport interface CullerPluginOptions\n{\n /**\n * Options for the culler behavior.\n * @example\n * ```ts\n * // Basic culling options\n * const app = new Application();\n * await app.init({\n * culler: {...}\n * });\n * ```\n */\n culler?: {\n /**\n * Update the transform of culled objects.\n *\n * > [!IMPORTANT] Keeping this as `false` can improve performance by avoiding unnecessary calculations,\n * > however, the transform used for culling may not be up-to-date if the object has moved since the last render.\n * @default true\n * @example\n * ```ts\n * const app = new Application();\n * await app.init({\n * culler: {\n * updateTransform: false // Skip updating transforms for culled objects\n * }\n * });\n * ```\n */\n updateTransform?: boolean;\n };\n}\n\n/**\n * An {@link Application} plugin that automatically culls (hides) display objects that are outside\n * the visible screen area. This improves performance by not rendering objects that aren't visible.\n *\n * Key Features:\n * - Automatic culling based on screen boundaries\n * - Configurable culling areas and behavior per container\n * - Can improve rendering performance\n * @example\n * ```ts\n * import { Application, CullerPlugin, Container, Rectangle } from 'pixi.js';\n *\n * // Register the plugin\n * extensions.add(CullerPlugin);\n *\n * // Create application\n * const app = new Application();\n * await app.init({...});\n *\n * // Create a container with culling enabled\n * const container = new Container();\n * container.cullable = true; // Enable culling for this container\n * container.cullableChildren = true; // Enable culling for children (default)\n * app.stage.addChild(container);\n *\n * // Optional: Set custom cull area to avoid expensive bounds calculations\n * container.cullArea = new Rectangle(0, 0, app.screen.width, app.screen.height);\n *\n * // Add many sprites to the group\n * for (let j = 0; j < 100; j++) {\n * const sprite = Sprite.from('texture.png');\n * sprite.x = Math.random() * 2000;\n * sprite.y = Math.random() * 2000;\n *\n * sprite.cullable = true; // Enable culling for each sprite\n *\n * // Set cullArea if needed\n * // sprite.cullArea = new Rectangle(0, 0, 100, 100); // Optional\n *\n * // Add to container\n * container.addChild(sprite);\n * }\n * ```\n * @remarks\n * To enable culling, you must set the following properties on your containers:\n * - `cullable`: Set to `true` to enable culling for the container\n * - `cullableChildren`: Set to `true` to enable culling for children (default)\n * - `cullArea`: Optional custom Rectangle for culling bounds\n *\n * Performance Tips:\n * - Group objects that are spatially related\n * - Use `cullArea` for containers with many children to avoid bounds calculations\n * - Set `cullableChildren = false` for containers that are always fully visible\n * @category app\n * @standard\n * @see {@link Culler} For the underlying culling implementation\n * @see {@link CullingMixinConstructor} For culling properties documentation\n */\nexport class CullerPlugin\n{\n /** @ignore */\n public static extension: ExtensionMetadata = {\n priority: 10,\n type: ExtensionType.Application,\n name: 'culler',\n };\n\n /** @internal */\n public static renderer: Renderer;\n /** @internal */\n public static stage: Container;\n /** @internal */\n public static render: () => void;\n private static _renderRef: () => void;\n\n /**\n * Initialize the plugin with scope of application instance\n * @private\n * @param {object} [options] - See application options\n */\n public static init(options?: PixiMixins.ApplicationOptions): void\n {\n this._renderRef = this.render.bind(this);\n\n this.render = (): void =>\n {\n // default to true for updateTransform, unless specified otherwise\n const updateTransform = options?.culler?.updateTransform !== true;\n\n Culler.shared.cull(this.stage, this.renderer.screen, updateTransform);\n this.renderer.render({ container: this.stage });\n };\n }\n\n /** @internal */\n public static destroy(): void\n {\n this.render = this._renderRef;\n }\n}\n"],"names":[],"mappings":";;;;AAqHO,MAAM,YACb,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBI,OAAc,KAAK,OACnB,EAAA;AACI,IAAA,IAAA,CAAK,UAAa,GAAA,IAAA,CAAK,MAAO,CAAA,IAAA,CAAK,IAAI,CAAA,CAAA;AAEvC,IAAA,IAAA,CAAK,SAAS,MACd;AAEI,MAAM,MAAA,eAAA,GAAkB,OAAS,EAAA,MAAA,EAAQ,eAAoB,KAAA,IAAA,CAAA;AAE7D,MAAA,MAAA,CAAO,OAAO,IAAK,CAAA,IAAA,CAAK,OAAO,IAAK,CAAA,QAAA,CAAS,QAAQ,eAAe,CAAA,CAAA;AACpE,MAAA,IAAA,CAAK,SAAS,MAAO,CAAA,EAAE,SAAW,EAAA,IAAA,CAAK,OAAO,CAAA,CAAA;AAAA,KAClD,CAAA;AAAA,GACJ;AAAA;AAAA,EAGA,OAAc,OACd,GAAA;AACI,IAAA,IAAA,CAAK,SAAS,IAAK,CAAA,UAAA,CAAA;AAAA,GACvB;AACJ,CAAA;AAAA;AAzCa,YAAA,CAGK,SAA+B,GAAA;AAAA,EACzC,QAAU,EAAA,EAAA;AAAA,EACV,MAAM,aAAc,CAAA,WAAA;AAAA,EACpB,IAAM,EAAA,QAAA;AACV,CAAA;;;;"}