It's "documented" as in "tweeted out by an Apple engineer": https://twitter.com/bciechanowski/status/874345241666437120?...

One thing that is not documented is that the IOSurface must have been created with the 'BGRA' pixel format, or it will silently render as black instead.

I hope that 'bgra' was at least a typo of 'rgba'

BGRA is a "weird" convention in the graphics world that goes back to at least OS/2 bitmaps, when there was no wrong answer, and has stuck since then. Since early GPUs targeted Windows (where BGRA is the native format for GDI/D2D), it makes sense that it made it this far :)

Do you have an FB number for improving the documentation here?

CALayer accepts a number of different data types for its contents property, IOSurface being one of them.

Another tip: CAShapeLayer draws on the GPU so simple shapes/strokes can be insanely faster drawn that way vs CoreGraphics.

It's not a private API, the docs are just out of date. You can technically set any object as the contents of a CALayer (the property's type is `id` or `Any`), it's just that most objects won't do anything productive.

The docs call out using images specifically because that's the 99% use-case; they need to be updated saying that `IOSurfaceRef`s can be used as layer content as well.

`IOSurfaceRef` itself was actually private at one point, IIRC, but isn't anymore.

> So we end up in a situation where using the most efficient way to display contents now relies on undocumented/private APIs. At any point Apple can break them, or punish us for using them.

Unless Apple wants to break all browsers, that is. At least Chrome and now Firefox use it.

They can make other browsers subtly slower, just open your imagination.