Graphics API - version 2 thoughts!

[GoodBoyDigital]

Hello all! So been reworking Graphics API a little and ended up creating a graphics context that exactly mimics the Canvas 2D context API. So my question to you.

Q1: Which API do you think is better?

a: The canvas API
b: The current PixiJS graphics API

Been noodling on this question for a while heres my top level thoughts

Canvas 2D API has a few really nice features

• DrawImage
• GradientFills / PatternFills are great
• Path2D is super awesome, especially support for SVG path is rad
• Stoke / fill functions are intuitive
• Familiar API, lots of resources on the web about how to use it!
• SVG support

Graphics API has a few nice features also

• Ability to easily work with holes
• Generally you can create and fill a shape with less code
• Using object syntax to set a line style is better setting single properties on canvas
• You can directly draw a primitive shape

Should we keep the original? Or switch to Canvas API? the have both? Should we cherry pick the best features from one and add to the other?

One problem that we think exists with both APIs is it can easily be abused to slow performance of rendering (i.e., “just enough rope for users to hang themselves”). There lots of historical comments on GitHub about rendering 10K circles or something silly.

Should we consider something like making individual display objects? Eg const myCircle = new CircleObject() ?

It would be great to get the community's thoughts on this! Additionally we are keen to understand

• Ways you feel we could improve on either API
• Is there a completely different approach to working with Graphics and shapes that we could look into?
• Most importantly - How you actually use Graphics and how essential it is to your projects. Would love to collect some use cases!

[miltoncandelero]

I would cherry pick. I think the flash api was the peak programmer friendlyness when it came to drawing primitives so I like the current API, however I like the inclusion for gradient fills and more cool toys.

Also to keep in mind, we use pixi to stay away from canvas, if a user wanted to do graphics with canvas they could create a canvas, use the canvas API and just make a texture 🤔

Finally, I think that Graphics is meant to be a somewhat vectory drawing API while canvas is a rastery one. That's why I don't think just putting the canvas API directly into pixi is the right approach.

[GoodBoyDigital]

Thanks for the feedback @miltoncandelero ! Really good points. especially the fact that ours is a vector API as opposed to a Rastery one!

Do you have any thoughts on what else we could add / improve? my head is right in this :D

[miltoncandelero]

This is the api we used to use for gradients in graphics.

https://books.openfl.org/openfl-developers-guide/using-the-drawing-api/creating-gradient-lines-and-fills.html

knowing the folks over at openFL that is lifted word by word from flash 😅

---

On the matter of "enough rope to hang yourself" I hung myself once trying to draw a tilemap tile with drawRect, performance tanked.
I wouldn't put too much pixel operations inside Graphics (if any). In any case, we might need another pixel manipulation object if we ever want to go that way 🤔

[andrewstart]

I agree with cherry picking - the largest missing component is probably gradients, which I recognize as challenging thing to solve. I once hacked together linear gradients in a rectangle for the predecessor of PixiAnimate (positioning and tinting vertices), and just that was a drag to implement.

[GoodBoyDigital]

nice! some good news there - I have patterns and gradients working like a boss for v8 :D. Your are totally right, uvs maths was tricky!

[bigtimebuddy]

I would like to make the case for creating primitive shape objects (e.g., CircleShape, RectangleShape, etc). Not super opinionated about the naming, "primatives", "shapes", "objects", "vectors". Many 3D libraries have setups like this and it makes it really easy to add things to the stage. Also, we would need a PathShape-type object which would contain all the lineTo, moveTo, for manual drawing. There are a couple reasons I think this is a better approach:

• Inherently more batcher-friendly, easer to share geometry
• Discourages abusing Graphics as single drawing surface, clearing repeatedly
• More dynamic, less static (tint, blendMode, transforms)
• Graphics class isn't overloaded with so much functionality
• We could potentially dynamically optimize curves in real-time

Plus, this could be 100% backward compatible with Graphics by making Graphics be a simple Container (e.g., drawCircle(x, y, radius) would drawCircle(x, y, radius) => this.addChild(new CircleShape(x, y, radius) instead).

Here's an example:

Current

import { Application, Graphics } from 'pixi.js';

const app = new Application();

const circle = new Graphics()
  .beginFill(0xff0000)
  .drawCircle(0, 0, 100)
  .endFill();

app.stage.addChild(circle);

Proposed

import { Application, CircleShape } from 'pixi.js';

const app = new Application();

app.stage.addChild(new CircleShape({
  radius: 100,
  fill: '#f00',
}));

[miltoncandelero]

How would you handle drawing what we would now do with move to + draws + fillls? 🤔

[bigtimebuddy]

We probably also need a generic PathShape that contains most of what's in Graphics (lineTo, moveTo, bezierCurveTo, drawPolygon, etc) but probably minus all the convenience draw-shapes methods (drawCircle, drawRectangle, drawShape, etc). I'm thinking about Babylon's Curve3 class. There are definitely legit use cases for having a flexible path drawing (eg data-viz).

[GoodBoyDigital]

i have a plan :D The way that Canvas' Path2D is implemented is exactly what we want! Plus would bring us new features...

• support for svg paths
• can be used to easily generate geometry to be used in meshes - which could power all the stand alone shapes :D

[ivanpopelyshev]

I'd like to point out that we actually have very good way of doing AA on simple shapes and masks made with them. easy things like "add circle to the stage without it being a separate graphics" should be taken into account.

[GoodBoyDigital]

thoughts on possible gradients API?

option 1: Object notation for a new function

gradientRect
      .rect(0, 0, 150, 150)
      .fillLinearGradient({
           x0:0, // start x point of gradient - optional, default 0
           y0:0, // start y point of gradient - optional, default 0
           x1:30, // end x point of gradient
           y1:30, // end x point of gradient
           colors:[0xFF0000, 0x00FF00, 0x0000FF], // colors to use
           stops:[0, 0.5, 1] // steps to switch colors - optional, default we spread the colors evenly
       })  

option 2: Create a gradient object (like Canvas does)

const gradient = new Gradient(0, 0, 30, 30)
.addColorStop(0xFF0000, 0)
.addColorStop(0x00FF00, 0.5)
.addColorStop(0x0000FF, 1)

gradientRect
      .rect(0, 0, 150, 150)
      .fill(gradient)  

option 3: Use same fill command with additional type

gradientRect
      .rect(0, 0, 150, 150)
      .fill({
           type: 'linear', // linear / radial / pattern etc.
           x0:0, // start x point of gradient - optional, default 0
           y0:0, // start y point of gradient - optional, default 0
           x1:30, // end x point of gradient
           y1:30, // end x point of gradient
           colors:[0xFF0000, 0x00FF00, 0x0000FF], // colors to use
           stops:[0, 0.5, 1] // steps to switch colors - optional, default we spread the colors evenly
       })  

curious to get people thoughts on this one! Do you have a favourite?

[bigtimebuddy]

There's some usefulness having a Gradient class because you can share them easily. But a class also means we can add operations, (e.g., reverse, reflect, etc) to the gradient's internal stops. And, I like that fill doesn't need to know about all the gradient options.

I look at this problem similar to TextStyle. I works as a vanilla object, but it's more powerful for creating shared styles if you use a TextStyle object.

Lastly, maybe consider both constructor(x0, y0, x1, y1) and constructor(options) as valid.

const gradient = new Gradient({
   type: 'linear', // linear / radial / pattern etc.
   x0:0, // start x point of gradient - optional, default 0
   y0:0, // start y point of gradient - optional, default 0
   x1:30, // end x point of gradient
   y1:30, // end x point of gradient
   colors:[0xFF0000, 0x00FF00, 0x0000FF], // colors to use
   stops:[0, 0.5, 1] // steps to switch colors - optional, default we spread the colors evenly
});
gradientRect
      .rect(0, 0, 150, 150)
      .fill(gradient) 

[bigtimebuddy]

Option 1 (i.e., fillLinearGradient) feels the least flexible, most coupled.

[GoodBoyDigital]

yeah, under the hood - it just ends up creating a standard fill style (with texture + uv matrix automatically generated)

[GoodBoyDigital]

Cool! Actually creating things like Gradient objects opens the door for other new and custom Patterns etc. They will just need to conform to an interface that contains a function that returns a 'FillStyle' :D

[miltoncandelero]

I look at this problem similar to TextStyle. I works as a vanilla object, but it's more powerful for creating shared styles if you use a TextStyle object.

I think that a similar approach to TextStyle could work wonders 🤔 👍

[GoodBoyDigital]

Just thinking out loud now ->

option 4: CSS?

gradientRect
      .rect(0, 0, 150, 150)
      .fill('linear-gradient(234deg, red 0%, blue 50%, green 100%)')

[GoodBoyDigital]

yeah, thats neat

[GoodBoyDigital]

Thanks all - last thought.. GraphicsGradient or Gradient ?

[miltoncandelero]

Thanks all - last thought.. GraphicsGradient or Gradient ?

Can we use it for anything else where we need a gradient? if not, either GraphicsGradient or if we have some sort of namespace graphics.Gradient otherwise people will jam a Gradient into Texts and everything will blow up 🥲

[GoodBoyDigital]

💥 good point! GraphicsGradient for now. This stuff can evolve as we go!

const gradient = new GraphicsGradient(0, 0, 0, 150)
    .addColorStop(0, '#FF0000')
    .addColorStop(0.5, '#00FF00')
    .addColorStop(1, '#0000FF')

const gradientRect = new Graphics()
    .rect(0, 0, 150, 150)
    .fill(gradient)  

gets us:

[bigtimebuddy]

I like FillGradient (e.g. FillPattern). We could use these outside Graphics.

[browsermage]

A thought is that if you use the Canvas2D API as a base the codebase will be smaller in size and "auto-magically" up to date when the Browser vendor updates their browser.