From 317cc97cb090913b76abe4601ae315d00f60ced9 Mon Sep 17 00:00:00 2001 From: Mat Groves Date: Wed, 21 Feb 2024 16:30:59 +0000 Subject: [PATCH] added final migration for v8 (#73) * added final migration for v8 * typo * typos * typo * final tweak --- docs/guides/migrations/v8.md | 174 ++++++++++++++++++++++++++++++++++- 1 file changed, 170 insertions(+), 4 deletions(-) diff --git a/docs/guides/migrations/v8.md b/docs/guides/migrations/v8.md index 0575b244a..f4fd99629 100644 --- a/docs/guides/migrations/v8.md +++ b/docs/guides/migrations/v8.md @@ -112,7 +112,144 @@ PixiJS will now need to be initialised asynchronously. With the introduction of With this change it also means that the `ApplicationOptions` object can now be passed into the `init` function instead of the constructor. ### **Graphics API Overhaul** -TODO: Mat + +There are a few key changes to the Graphics API. In fact this is probably the most changed part of v8. We have added deprications where possible but below is the rundown of changes: + +- Instead of beginning a fill or a stroke and then building a shape, v8 asks you to build your shape and then stroke / fill it. The terminology of `Line` has been replaced with the terminology of `Stroke` + +**Old** +```ts +// red rect +const graphics = new Graphics() + .beginFill(0xFF0000); + .drawRect(50, 50, 100, 100); + .endFill(); + +// blur rect with stroke +const graphics2 = new Graphics() + .lineStyle(2, 'white'); + .beginFill('blue'); + .circle(530, 50, 140, 100); + .endFill(); + +``` +**New** +```ts +// red rect +const graphics = new Graphics() + .rect(50, 50, 100, 100) + .fill(0xFF0000) + + +// blur rect with stroke +const graphics2 = new Graphics() + .rect(50, 50, 100, 100) + .fill('blue') + .stroke({width:2, color:'white'}) +``` + +- Shape functions have been renamed. Each drawing function has been simplified into a shorter version of its name. They have the same parameters though: + +| v7 API Call | v8 API Equivalent | +|------------------------|-------------------| +| drawChamferRect | chamferRect | +| drawCircle | circle | +| drawEllipse | ellipse | +| drawFilletRect | filletRect | +| drawPolygon | poly | +| drawRect | rect | +| drawRegularPolygon | regularPoly | +| drawRoundedPolygon | roundPoly | +| drawRoundedRect | roundRect | +| drawRoundedShape | roundShape | +| drawStar | star | + +- fills functions expect `FillStyle` options or a color, rather than a string of parameters. This also replaces `beginTextureFill` +**Old** +```ts + const rect = new Graphics() + .beginTextureFill({texture:Texture.WHITE, alpha:0.5, color:0xFF0000}) + .drawRect(0, 0, 100, 100) + .endFill() + .beginFill(0xFFFF00, 0.5) + .drawRect(100, 0, 100, 100) + .endFill() + +``` +**New** +```ts + const rect = new Graphics() + .rect(0, 0, 100, 100) + .fill({texture:Texture.WHITE, alpha:0.5, color:0xFF0000}) + .rect(100, 0, 100, 100) + .fill({color:0xFFFF00, alpha:0.5}) +``` + +- stokes functions expect `StrokeStyle` options or a color, rather than a string of parameters. This also replaces `lineTextureStyle` +**Old** +```ts + const rect = new Graphics() + .lineTextureStyle({texture:Texture.WHITE, width:10, color:0xFF0000}) + .drawRect(0, 0, 100, 100) + .endFill() + .lineStyle(2, 0xFEEB77); + .drawRect(100, 0, 100, 100) + .endFill() + +``` +**New** +```ts + const rect = new Graphics() + .rect(0, 0, 100, 100) + .stroke({texture:Texture.WHITE, width:10, color:0xFF0000}) + .rect(100, 0, 100, 100) + .stroke({color:0xFEEB77, width:2}) +``` + +- holes now make use of a new `cut` function. As with `stroke` and `fill`, `cut` acts on the previous shape. +**Old** +```ts + const rectAndHole = new Graphics() + .beginFill(0x00FF00) + .drawRect(0, 0, 100, 100) + .beginHole() + .drawCircle(50, 50, 20) + .endHole() + .endFill(); +``` +**New** +```ts + const rectAndHole = new Graphics() + .rect(0, 0, 100, 100) + .fill(0x00FF00) + .circle(50, 50, 20) + .cut(); +``` + + +- `GraphicsGeometry` has been replaced with `GraphicsContext` this allows for sharing of `Graphics` data more efficiently. +**Old** +```ts + const rect = new Graphics() + .beginFill(0xFF0000); + .drawRect(50, 50, 100, 100); + .endFill(); + + const geometry = rect.geometry; + + const secondRect = new Graphics(geometry); + +``` +**New** +```ts + const context = new GraphicsContext() + .rect(50, 50, 100, 100) + .fill(0xFF0000) + + const rect = new Graphics(context); + const secondRect = new Graphics(context); +``` + ### Other Breaking Changes @@ -149,10 +286,39 @@ TODO: Mat ``` - Mipmap generation changes - - TODO: MAT + - The BaseTexture `mipmap` property has been renamed to `autoGenerateMipmaps`. + - Mipmaps for `RenderTextures` have been adjusted so that developer is responsible for updating them mipmaps. Mipmap generation can be expensive, and due to the new reactive way we handle textures we do not want to accidentally generate mipmaps when they are not required. + +```ts +const myRenderTexture = RenderTexture.create({width:100, height:100, autoGenerateMipmaps:true}) + +// do some rendering.. +renderer.render({target:myRenderTexture, container:scene}) + +// now refresh mipmaps when you are ready +myRenderTexture.source.updateMipmaps(); +``` + + +- Due to the new way PixiJS handles things internally, sprites no longer get notified if a texture's UVs have been modified. The best practice is not to modify texture UVs once they have been created. It's best to have textures ready to go (they are inexpensive to create and store). +- Sometimes, you might want to employ a special technique that animates the UVs. In this last instance, you will be responsible for updating the sprite (it's worth noting that it may update automatically - but due to the new optimizations, this will not be guaranteed). Updating the source data (e.g., a video texture) will, however, always be reflected immediately. + +```ts +const texture = await Assets.load('bunny.png'); +const sprite = new Sprite(texture); + +texture.frame.width = texture.frame.width/2; +texture.update(); + +// guarantees the texture changes will be reflected on the sprite +sprite.onViewUpdate(); + + +// alternatively you can hooke into the sprites event +texture.on('update', ()=>{sprite.onViewUpdate}); +``` -- TODO: something to do with calling `onUpdate` manually if you change a textures properties - - https://github.com/pixijs/pixijs/pull/9803 +The act of adding and removing the event when a sprite's texture was changed led to an unacceptable performance drop, especially when swapping many textures (imagine shooting games with lots of keyframe textures swapping). This is why we now leave that responsibility to the user. - New Container culling approach