SampleBufferVideoRenderer

Presents frames into an AVSampleBufferDisplayLayer, on iOS and on macOS.

This layer exists for one reason: it is the only content a picture in picture controller accepts from a player that is not the system player. The Metal renderer stays the general path, and this one is chosen when the application wants the small window.

Frames arrive as pixel buffers. A hardware frame already is one and is retained rather than copied. A software frame is copied into one, which costs a pass over the picture, so this renderer earns its price only while the small window matters.

The engine paces, not the layer. Every sample is marked to display at once, so the video scheduler stays the single authority on when a frame shows. The layer can still carry a control timebase: the picture in picture window reads its progress from that clock, and the mark keeps the clock from holding frames back.

Subtitles are drawn into the picture. The layer shows sample buffers and nothing else, and the small window shows only the layer. So while an overlay has text, the picture and the text are composed on the GPU into a new pixel buffer, and that buffer is shown instead. A subtitle change redraws the picture on screen, so a paused picture gains or loses its text at once. A picture that its frame or the viewer turns or mirrors is composed the same way, text or not, because the layer shows a buffer as it is stored. Without a Metal device the text is left out, and the picture shows as it is stored.

On macOS 14, iOS 17 and later, the layer's own video renderer takes the samples on the calling thread. Before that, the layer takes them itself, on the main queue. Apple asks for one of the two per layer, never both.

Formats: NV12, planar 4:2:0 whose chroma is interleaved on the way in, and BGRA. Anything else is refused, which the engine counts as a dropped frame rather than a failure.

The picture controls in io.github.yuroyami.kiteplayer.VideoAdjustments are not applied here: the layer shows the decoded picture as it is.