update

docs/guides/advanced/garbage-collection.md

@@ -0,0 +1,125 @@
+import Example from '@site/src/components/Example/index';
+import version from '@site/docs/pixi-version.json';
+
+# Understanding Garbage Collection in PixiJS
+
+Garbage collection (GC) in PixiJS ensures GPU resources are efficiently managed by cleaning up assets no longer in use. While JavaScript developers are accustomed to automatic memory management, GPU resources need explicit cleanup to avoid resource leaks and performance degradation. PixiJS provides two systems to help manage this: `RenderableGCSystem` and `TextureGCSystem`.
+
+These systems act as a safety net, cleaning up unused resources over time to prevent the GPU from filling up. However, developers can and should manually manage resources where possible for better control.
+
+---
+
+### What You’ll Learn
+
+- How the `RenderableGCSystem` and `TextureGCSystem` work.
+- Configuring the GC systems via the `init` function.
+- Best practices for managing GPU resources.
+- Why GC is crucial for efficient GPU usage.
+
+---
+
+### The Basics of Garbage Collection
+
+#### Why is Garbage Collection Important?
+
+The GPU does not automatically release resources when they’re no longer needed. Without explicit cleanup, textures, buffers, and other resources can accumulate, causing memory leaks and reduced performance. While PixiJS provides GC systems as a safety net, manual management (e.g., calling `destroy()` on unused assets) is the best way to ensure efficient GPU usage.
+
+---
+
+### PixiJS Garbage Collection Systems
+
+#### RenderableGCSystem
+
+The `RenderableGCSystem` handles cleanup of GPU resources for renderable objects like sprites, text, and graphics.
+
+Key features:
+- Cleans up unused renderables after a specified idle time (default: 60 seconds).
+- Runs periodically based on a configurable frequency (default: every 30 seconds).
+- Works independently of rendering, ensuring cleanup even during idle periods.
+
+Configuration example:
+```javascript
+const renderer = new PIXI.Renderer();
+renderer.use(new PIXI.RenderableGCSystem());
+
+renderer.init({
+    renderableGCActive: true,       // Enable/disable the system
+    renderableGCMaxUnusedTime: 60000, // Maximum idle time before cleanup
+    renderableGCFrequency: 30000,     // Frequency of GC checks
+});
+```
+
+#### TextureGCSystem
+
+The `TextureGCSystem` manages textures loaded into the GPU and cleans up those not used for a specified number of frames.
+
+Key features:
+- Cleans up textures after a specified number of idle frames (default: 60 frames).
+- Runs periodically based on a configurable frame count (default: every 600 frames).
+- Targets textures marked with `autoGarbageCollect: true`.
+
+Configuration example:
+```javascript
+const renderer = new PIXI.Renderer();
+renderer.use(new PIXI.TextureGCSystem());
+
+renderer.init({
+    textureGCActive: true,            // Enable/disable the system
+    textureGCMaxIdle: 3600,          // Maximum idle frames before cleanup
+    textureGCCheckCountMax: 600,     // Frames between GC checks
+});
+```
+
+---
+
+### Best Practices for GPU Resource Management
+
+1. **Manual Cleanup**: Always call `destroy()` on unused objects (e.g., `sprite.destroy()`) to explicitly free resources.
+2. **Enable GC Systems as a Safety Net**: The GC systems ensure resources are cleaned up if manual cleanup is missed.
+3. **Adjust GC Frequency for Your Application**: If your application frequently creates and destroys resources, you may need to increase or decrease the GC frequency.
+4. **Monitor Resource Usage**: Use tools like Chrome DevTools or WebGL Inspector to monitor GPU resource usage and detect leaks.
+
+---
+
+### Example: Managing GPU Resources with GC
+
+```javascript
+const renderer = new PIXI.Renderer();
+renderer.use(new PIXI.RenderableGCSystem());
+renderer.use(new PIXI.TextureGCSystem());
+
+renderer.init({
+    renderableGCActive: true,
+    renderableGCMaxUnusedTime: 60000,  // 1 minute idle time for renderables
+    renderableGCFrequency: 30000,      // Check every 30 seconds
+    textureGCActive: true,
+    textureGCMaxIdle: 3600,           // 1 minute idle time for textures
+    textureGCCheckCountMax: 600,      // Check every 600 frames
+});
+
+// Example: Creating and destroying a sprite
+const texture = PIXI.Texture.from('example.png');
+const sprite = new PIXI.Sprite(texture);
+
+renderer.render(sprite);
+sprite.destroy(); // Proper cleanup to release resources
+```
+
+---
+
+### Gotchas
+
+- **GC is Not a Replacement for Manual Cleanup**:
+  - Always call `destroy()` or equivalent methods to release resources when they are no longer needed.
+- **Adjust for Performance**:
+  - Overly aggressive GC settings can lead to unnecessary resource reallocation, while too lenient settings may cause memory issues.
+- **Check Resource Markers**:
+  - Only objects marked with `autoGarbageCollect: true` will be managed by the GC systems.
+
+---
+
+### Conclusion
+
+Garbage collection in PixiJS helps manage GPU resources efficiently, acting as a safety net for unused resources. While developers should always aim to manage resources manually, the `RenderableGCSystem` and `TextureGCSystem` provide robust tools to prevent GPU overload. With proper configuration and best practices, you can ensure smooth performance and prevent resource leaks in your PixiJS applications.
+
+For advanced use cases, these systems can also be disabled, allowing developers full control over resource management. Whether you use them as a safety net or as part of your workflow, understanding PixiJS’s GC systems is key to building performant applications.

docs/guides/components/graphics-fill.md

@@ -1,6 +1,6 @@
 # Graphics Fill
 
-Graphics in PixiJS are incredibly versatile, allowing developers to achieve stunning visual effects. The `fill()` method is particularly powerful, enabling you to fill shapes with colors, textures, or gradients. Whether you're designing games, UI components, or creative tools, mastering the `fill()` method is essential for creating visually appealing and dynamic graphics. This guide explores the different ways to use the `fill()` method to achieve stunning visual effects.
+If you are new to graphics, please check out the [graphics guide](./graphics) here. This guide dives a bit deeper into a specific aspect of graphics: how to fill them! The `fill()` method in PixiJS is particularly powerful, enabling you to fill shapes with colors, textures, or gradients. Whether you're designing games, UI components, or creative tools, mastering the `fill()` method is essential for creating visually appealing and dynamic graphics. This guide explores the different ways to use the `fill()` method to achieve stunning visual effects.
 
 :::info Note
 The `fillStyles` discussed here can also be applied to Text objects!
@@ -63,9 +63,7 @@ Filling shapes with textures is just as simple:
 ```ts
 let texture = await Assets.load('assets/image.png');
 let obj = new Graphics().rect(0, 0, 100, 100)
-  .fill({
-    texture: texture,
-  });
+  .fill(texture);
 ```
 
 ![alt text](image-2.png)
@@ -113,9 +111,7 @@ let spriteSheetTexture = Texture.from('assets/my-sprite-sheet.png');
 let newTexture = renderer.generateTexture(Sprite.from(spriteSheetTexture));
 
 let obj = new Graphics().rect(0, 0, 100, 100)
-  .fill({
-    texture: newTexture,
-  });
+  .fill(newTexture);
 ```
 
 2. **Power of Two Textures**: Textures should be power-of-two dimensions for proper tiling in WebGL.
@@ -138,9 +134,7 @@ let gradient = new FillGradient({
 });
 
 let obj = new Graphics().rect(0, 0, 100, 100)
-  .fill({
-    fill: gradient,
-  });
+  .fill(gradient);
 ```
 
 ![alt text](image-5.png)
@@ -178,6 +172,9 @@ let gradient = new FillGradient({
     { offset: 1, color: 'green' },
   ],
 });
+
+let obj = new Graphics().rect(0, 0, 100, 100)
+  .fill(gradient);
 ```
 
 ![alt text](image-7.png)
@@ -204,6 +201,9 @@ let radialGradient = new FillGradient({
     { offset: 1, color: 'red' },
   ],
 });
+
+let obj = new Graphics().rect(0, 0, 100, 100)
+  .fill(gradient);
 ```
 
 ![alt text](image-8.png)
@@ -216,21 +216,44 @@ let radialGradient = new FillGradient({
 
 3. **Custom Shaders**: For complex animations, custom shaders may be more efficient.
 
+4. **Texture and Matrix Limitations**: Under the hood, gradient fills set both the texture and matrix properties internally. This means you cannot use a texture fill or matrix transformation at the same time as a gradient fill.
+
 ### Combining Textures and Colors
 You can combine a texture or gradients with a color tint and alpha to achieve more complex and visually appealing effects. This allows you to overlay a color on top of the texture or gradient, adjusting its transparency with the alpha value. 
 
+```ts
+
+let gradient = new FillGradient({
+    colorStops: [
+        { offset: 0, color: 'blue' },
+        { offset: 1, color: 'red' },
+    ]
+});
+
+let obj = new Graphics().rect(0, 0, 100, 100)
+  .fill({
+    fill: gradient,
+    color: 'yellow',
+    alpha: 0.5,
+  });
+
+```
+
+![alt text](image-10.png)
+
 ```ts
 let obj = new Graphics().rect(0, 0, 100, 100)
   .fill({
     texture: texture,
     color: 'yellow',
     alpha: 0.5,
   });
+
 ```
 
 ![alt text](image-9.png)
 
 ---
 
-By mastering the `fill()` method, you can unlock endless possibilities for creating visually dynamic and engaging graphics in PixiJS. Have fun!
+Hopefully, this guide has shown you how easy and powerful fills can be when working with graphics (and text!). By mastering the `fill()` method, you can unlock endless possibilities for creating visually dynamic and engaging graphics in PixiJS. Have fun!