High-level scene API

[ascent12]

Over time, I've been pushing to make many of our API lower-level and efficient as they could reasonably be. Unfortunately, this does make things much harder to use, especially for people without specialised knowledge, making the barrier to entry still very high for using wlroots.

Basically, I think we need a restricted "easy mode" API that can help people still do everything as efficiently as possible (all handled internally). This honestly wouldn't be that different than WLC or a parts of libweston.

Instead of the user handling rendering with damage tracking, planes, and all that shit we want to add, they just say "the window goes here".

I don't know how high-level this really should be. Should this handle shells, drag-and-drop, or other complex operations? Does this even belong in wlroots itself or should it exist as a layered library in its own repository?

The name I was thinking for it is wlr_desktop.

[AdrianVovk]

I think a separate library would be the best place for this. The should also be a way to hook into wlroots itself if the user chooses to do something a bit more custom sometimes

[ascent12]

I was leaning towards external too. Adding some ways to "go lower" would be nice, but we need to be careful to not make doing that really complex, defeating the purpose of the API.

[ddevault]

I think we would need a more detailed design doc written up before we could judge whether to include it in wlroots or not.

Rather than wlr_desktop, which implies a focus on the desktop use-case, I'd prefer wlr_scene.

[emersion]

+1 for wlr_scene. I think such a helper would make planes a lot less annoying to use. It could just be a bunch of buffers to draw at certain positions (ala libliftoff).

[bl4ckb0ne]

Hi there, I'm working on https://git.sr.ht/~bl4ckb0ne/wltrunk, a library based on wlroots that aims to bring a higher level API. I'll gladly discuss anything on either irc (i'm on #sway-devel with the same handle) or by mail.

[ddevault]

I don't think I would like to see the scene API end up in wltrunk.

[emersion]

Note that wlr_scene could simplify damage tracking and could allow us not to draw regions of buffers hidden behind other opaque buffers.

[ascent12]

I've seriously been thinking about implementing this.
Basically, I need a proving ground for #1685 + #1818. I need a "real" compositor to work with, but changing something like sway would be a a hassle, especially since I wanted to add this anyway.
This would also mean fewer massive breaking changes for users, but also a much bigger pull request to review.

I haven't come up with a C API, but a have list of ideas, none of which are particularly original.

Use case

• It will be strictly optional.
• The use case is very strict. Basic 2D Wayland compositors. I'm not going to complicate the design for features beyond that. This relates to the above point; if you want to do special shit, you're just going to have to do it yourself.

Protocols

• It will not implement any shells. It will purely work with wlr_surfaces, and will just put things where it's told. Sub-surfaces (which technically count as a shell) may be an exception to this; I'll have to think about it.
• It will implement many protocols related to rendering and presentation. Presentation time, colour management, viewporter, anything like that.

Rendering

• It will not support arbitrary surface transforms with matrices or even arbitrary surface rotation. It just adds so much complexity (especially to damage tracking) for such little gain. We still need 90/180/270 + reflect x/y for protocol compliance, but they're significantly easier.
• No hooks or callbacks will exist for changing the rendering behaviour.
• It will use libliftoff internally (with overlay support added to the backends).

Scene-graph

• It will be layer based. Not the strict static way layer-shell is, and you can create an arbitrary number of layers at any time around and rearrange them freely, but obviously this helps compositors use layer-shell.
• You create a view as a representation of the surface in the scene. You then put the view onto a layer.
• You can also create views not tied to surfaces, so the compositor can put their own drawings in there. It would be useful for server-side decorations. It would probably be strictly CPU-uploaded data, and maybe setting a single colour.

Atomic updates

• Like sway's transactions, I want to be able to transition between two configurations in one go. This is a missing feature I find very annoying about libweston.
• Since we can't guarantee that a client is going to resize in time (if at all), we will need a way for users to deal with that. I have some vague ideas of a signal right before drawing time for the user to check the configuration, and make some last-minute changes if they need to.

Cursor

I don't know if I want to make a special provisions for cursors or not.

• Make them be equivalent to any other view, and the user just puts it on the top layer. The scene will then take whatever the top view is (even if it's not a cursor) and tries to put it on the cursor plane if it can.

OR

• Add a special type of view with hotspot handling that is known to always be above other views and possibly be unsynchronized.

The first is much cleaner but it only works if the cursor is synchronized with the rest of the presentation. That is only true on the DRM backend.
If we're using the Wayland or X11 backend, and we try to use some arbitrary surface as the cursor, that's going to look extremely stupid. Also, we don't have access to the hotspot, so even if we do use the real cursor, it'll be in the wrong place.
That's the reason that weston always draws its own software cursor in that case.

Outputs

• Separate the idea of a "drawing region" from a real output, but each output has it's own drawing region.
• A drawing region is basically a swapchain that has all of the damage tracking applied to it. A viewport into the scene.
• Can be placed anywhere on the scene.
• Allows us to do screen capture spanning across real outputs or even the entire scene.

More radical ideas

• Remove wlr_renderer from our API
• wlr_scene effectively deprecates wlr_renderer, because it's a better way for the same use case.
• Rather than a set of basic drawing operations, it consumes the scene graph and draws to a drawing region.
• Allows for a Vulkan renderer to work in a way that suits it better (e.g. using command buffers effectively), instead of being tied to the current stateful API.
• Still requires renderer v6.
• Still keep renderer types like wlr_egl for people that are doing it themselves.

[ddevault]

This is an excellent draft, I'm really excited about it. A few questions occur to me:

• How would a compositor do something like rendering window borders? Would they have to create a surface for them? Sway does this now by rendering borders to a wlr_texture and drawing it through the renderer.
• Will it be one surface per layer? Will the compositor have to manage N layers themselves, where N is every surface (and subsurface?), be it top-levels or layer clients or w/e

[ascent12]

How would a compositor do something like rendering window borders? Would they have to create a surface for them? Sway does this now by rendering borders to a wlr_texture and drawing it through the renderer.

Create a colour or image view (i.e. not attached to a wl_surface) and then place then around the edge of the surface you want to decorate.

(Blue is clients contents view, green is image/color view, red is hypothetical border drawn)

The first style would be for compositors that want rounded corners. They could even load those images from a PNG or something, and make it customisable for the end users.

The second style would work for sway, and they would just be color views.

The third is even simpler, but does put colour data behind the client surface, messing with their transparency a bit.

Will it be one surface per layer? Will the compositor have to manage N layers themselves, where N is every surface (and subsurface?), be it top-levels or layer clients or w/e

An arbitrary number of surfaces per layer, and you could even put layers on other layers. They will just be a useful way of grouping various views together in a hierarchy.

Here is what an example scene graph on sway might look like, with 2 clients open:

(I realised I forgot to add a floating layer, but just imagine it's there).
Each layer maintains an stacking order between its children. While layers don't conceptually have a width or height, they do have a position. All of its children would be placed relative to that position, and moving a layer or removing it from the scene will affect all of its descendents.

In the example, all of the layers besides "root" are completely arbitrary and is not enforced by wlr_scene. A user might organise it that way because it's convenient.

wlr_scene will walk the tree at rendering time and flatten it into an absolute stack of views, and use that for rendering.

[ammen99]

• Remove wlr_renderer from our API
• wlr_scene effectively deprecates wlr_renderer, because it's a better way for the same use case.
• Rather than a set of basic drawing operations, it consumes the scene graph and draws to a drawing region.

Wayfire needs a single rendering operation from wlroots: Render a surface texture to a given framebuffer with a given scissor region.

Currently, wlr_renderer does a good job for that (although it technically may change the active framebuffer, but current implementation doesn't). It also helps me abstract away the different types of textures - I don't care about EGLImages, or buffer uploading, or anything like this. So I would prefer to have wlr_renderer, even if you strip down some of its functionality.

If you do decide that it is really nice for wlroots to remove wlr_renderer, then at least make sure the compositor has access to the OpenGL texture of each surface.

[ascent12]

I don't care about EGLImages, or buffer uploading, or anything like this
then at least make sure the compositor has access to the OpenGL texture of each surface

As a Wayland compositor, you kind of have to care, especially when getting to the level of textures. It's just the nature of what we're doing.

With wlr_renderer gone, there are no OpenGL textures for each surface. You are the one responsible for doing that.

The idea for custom renderers was always supposed to be that you have your low-level client buffers (dmabufs and shm), and you do with them whatever you want to, using whatever dmabuf-capable API you want. It should be possible to write a Vulkan Wayland compositor without touching a single piece of EGL or OpenGL. You could even write a Wayland compositor that only ever tries to use direct scanout and planes, and doesn't even have a renderer.

wlr_egl will still exist as a separate type to deal with EGL, including getting an EGLImage from client buffers. A helper for uploading damaged regions for wl_shm is something that exists on some PR of mine. Maybe some other helpers that make sense can be added.

But a helper for OpenGL textures is just not something I can write. It touches more areas than just texture uploads. In order to do it properly, I need a hand in a bunch of other calls you make, as well as in your shaders. wlr_texture was never supposed to be this helper, and any API requiring an extra unnecessary copy to do anything useful is not something I find acceptable.

Most of the useful OpenGL things our renderer does requires touching the shaders, and a shader generator library is something I REALLY don't want to have.

---

A helper specifically for the OpenGL part of handling EGLImages isn't even necessary in my opinion, because it's actually pretty simple, at least compared to the rest of OpenGL. You just have to know where to start.

If you want to read from an EGLImage:

OES_EGL_image_external / OES_EGL_image_external_essl3
The essl3 is a layered extension for when you're using the OpenGL ES Shading Language version 3, and just defines some extra interactions with that.

GLuint tex;
glGenTextures(1, &tex);
glBindTexture(GL_TEXTURE_EXTERNAL_OES, tex);
glEGLImageTargetTexture2DOES(GL_TEXTURE_EXTERNAL_OES, egl_image);

and you have a texture you can use.
The target parameter for future texture calls are GL_TEXTURE_EXTERNAL_OES instead of GL_TEXTURE_2D but are otherwise the same.
In the shader, you need to #extension GL_OES_EGL_image_external : require, and the sampler type is samplerExternalOES instead of sampler2D.
There are a couple of other restrictions on some functions you can call, mostly stopping you from writing to the texture. They're listed in the spec.

If you want to draw to an EGLImage:

OES_EGL_image

This one is even easier.

GLuint tex;
glGenTextures(1, &tex);
glBindTexture(GL_TEXTURE_2D, tex);
glEGLImageTargetTexture2DOES(GL_TEXTURE_2D, egl_image);

And that's it. It acts completely like a normal texture after this; attach it to your framebuffer object and start drawing like normal.

You can do it as a renderbuffer too.

GLuint rb;
glGenRenderbuffers(1, &rb);
glBindRenderbuffer(GL_RENDERBUFFER, rb);
glEGLImageTargetRenderbufferStorageOES(GL_RENDERBUFFER, egl_image);

Renderer v6 plans to drop EGLSurfaces, meaning you lose the default framebuffer. Drawing to gbm_bos through EGLImages will actually become a requirement.

[ammen99]

wlr_texture was never supposed to be this helper, and any API requiring an extra unnecessary copy to do anything useful is not something I find acceptable.

But I find it acceptable since I need to do it (even if I had access to texture/EGLImage/whatever).

Anyway I see that you want to do a large refactoring of the rendering code both in wlroots and compositors. Just ping me when your changes are ready, so I can try to update Wayfire and see whether I can get all I need. In the worst case, I'll end up copying most of wlr_renderer to Wayfire.

[emersion]

It will purely work with wlr_surfaces

I understand you want wlr_surfaces to be able to do explicit synchronization stuff. I'm not sure it's a good idea for a first step, maybe we should start with wlr_buffers and expand to wlr_surfaces later.

It will be layer based. Not the strict static way layer-shell is, and you can create an arbitrary number of layers at any time around and rearrange them freely, but obviously this helps compositors use layer-shell.

Why are layers necessary? Why not just set a z-index on each view?

You can also create views not tied to surfaces, so the compositor can put their own drawings in there. It would be useful for server-side decorations. It would probably be strictly CPU-uploaded data, and maybe setting a single colour.

+1

It would be nice to also allow for custom GPU data too. Making wlr_buffer an interface could help.

Since we can't guarantee that a client is going to resize in time (if at all), we will need a way for users to deal with that. I have some vague ideas of a signal right before drawing time for the user to check the configuration, and make some last-minute changes if they need to.

Hmm. Sway shows a "saved" wlr_buffer when the layout changes. I wonder how that fits in this design.

Remove wlr_renderer from our API

Side note, we still need to keep the wlr_texture part of the renderer. Hmm, it seems (from your later comments) like you want to make this private to wlr_scene?

(More on this below)

Still requires renderer v6.

Well this design doesn't require renderer v6. We could land the groundwork for this with the current renderer infrastructure.

An arbitrary number of surfaces per layer, and you could even put layers on other layers. They will just be a useful way of grouping various views together in a hierarchy.

Hmm. Why not just set an "absolute" position on views instead?

A tree seems a little bit complicated and I'm not sure it'd be really useful.

A helper specifically for the OpenGL part of handling EGLImages isn't even necessary in my opinion, because it's actually pretty simple, at least compared to the rest of OpenGL.

Here comes multi-planar textures...

But a helper for OpenGL textures is just not something I can write. It touches more areas than just texture uploads. In order to do it properly, I need a hand in a bunch of other calls you make, as well as in your shaders. wlr_texture was never supposed to be this helper, and any API requiring an extra unnecessary copy to do anything useful is not something I find acceptable.

Hmm. I have to agree with @ammen99 here. See #1904 for a potential solution.

[ascent12]

I understand you want wlr_surfaces to be able to do explicit synchronization stuff. I'm not sure it's a good idea for a first step, maybe we should start with wlr_buffers and expand to wlr_surfaces later.

The scene is supposed to handle everything involving presentation, including wl_surface.frame and wp_presentation_feedback. It really needs to the whole surface. Handling only buffers is a completely different design.
There is a reason I put "high-level" in the title.

Hmm. Sway shows a "saved" wlr_buffer when the layout changes. I wonder how that fits in this design.

I'd have to try and actually implement it to see what kind of issues arise and how much wlr_scene can do vs what the user has to do.

it seems (from your later comments) like you want to make this private to wlr_scene?

Yes.

Well this design doesn't require renderer v6. We could land the groundwork for this with the current renderer infrastructure.

I definitely should have phrased that better: it doesn't obsolete renderer v6. This can be implemented on top of the current EGL stuff we already have.

Why are layers necessary? Why not just set a z-index on each view?
Hmm. Why not just set an "absolute" position on views instead?
A tree seems a little bit complicated and I'm not sure it'd be really useful.

It's an ergonomics thing. Remember that the use case for this is intended to be very strict: basic 2D Wayland compositors.
I'm sure if we did this as a flat list, 99% of compositors are just going to implement a tree of some sort in their own data structures anyway, because that's basically how layer-shell wants you to design it, and it's quite a natural way to think of 2D anyway.

It also provides a useful form of grouping. Subsurfaces are defined as a tree, and can be represented easily here too. When putting a view on top of another, instead of looking for the subsurface which is the highest and putting it on top of that, you can just "put it on top of the layer these subsurfaces are all on".

Subsurfaces are also the reason it uses relative positioning. You can move the group around easily without having to go through and move each one individually.

Here comes multi-planar textures...

Fundamentally the same. There's just more than one EGLImage/texture. The more complex bit is using them in your shaders.

Hmm. I have to agree with ammen99 here. See #1904 for a potential solution.

As I mentioned on IRC, this would be more for some "OpenGL toolkit" kind of interface, rather than being bolted-on to wlr_renderer. If you're just reaching in and taking all of the GL texture ids out, then what is the renderer even doing?

[ddevault]

The main reason to keep wlr_texture around is that there are many ways to skin that particular cat, and you'll be responsible for all of them if we take the API out. That means implementing shm, wl_drm, and linux-dmabuf yourself, not to mention anything else that comes up later.

[ascent12]

That's the nature of writing a renderer for a Wayland compositor, though. The "batteries not included" design of wlroots was supposed to allow you to see those gory details. And then we have helpers for common things where it makes sense.

wlr_renderer + wlr_texture is helper is at a level where it doesn't make sense. It's been one of the most restrictive things in our design, but has always been a necessary evil. I've wanted to kill it before we even added it.

BUT I do think an equivalent that specifically targeted OpenGL would make a lot more sense; not some half-ass abstraction that it currently is. Basically something that is responsible for spitting out GL textures that people writing custom renderers can use, and maybe not a lot else. You wouldn't need pixel uploading, drawing quads, scissor regions or any of that.

[ddevault]

I'm on the fence. The prime directive of wlroots is to reduce the workload on compositors without doing anything that prevents them from taking the wheel when they need to. I think that this code is going to end up looking basically identical for all compositors, and non-trivial to boot. I'd be interested in seeing what @emersion's proposed experiment turned out.

[ascent12]

When it comes to huge things like OpenGL, I think the better thing to do is to just get out of the way and let people write OpenGL. I don't think people writing their own renderers want us to write it for them by layering a bunch of stuff on top of it.
All we need to do is provide the integration bits, so they can actually be a Wayland compositor.

[ddevault]

I would agree totally if the question were only about wl_shm, where the most work you have to do with OpenGL is uploading pixels, which everyone else does. But wl_drm and linux-dmabuf are both Wayland specific and require some extra thought and attention, which is where wlroots seems to naturally come in.

[ascent12]

I agree. That falls under "something that is responsible for spitting out GL textures" and "the integration bits".

[emersion]

The scene is supposed to handle everything involving presentation, including wl_surface.frame and wp_presentation_feedback. It really needs to the whole surface. Handling only buffers is a completely different design.
There is a reason I put "high-level" in the title.

Mind, the two (allowing to attach wlr_surface or wlr_buffer) aren't exclusive. We already have different "view types" (solid color, compositor buffer) so having a wlr_surface and a wlr_buffer would be almost free.

Having both would allow compositors that would want to have more control over the displayed buffer (e.g. current Sway) to do it without issues. It would also allow compositors to implement custom frame scheduling without throwing away everything.

When putting a view on top of another, instead of looking for the subsurface which is the highest and putting it on top of that, you can just "put it on top of the layer these subsurfaces are all on".

I'd expect compositors to iterate over all of their view surfaces and update the wlr_scene with their internal state.

[emersion]

I'm still wondering what the interface with the backend should be. The scene would need to interface with DRM planes and Wayland subsurfaces.

• The backend could directly get a pointer to the scene graph. It's a simple solution but it would require the backend to potentially handle high-level stuff it doesn't need, like the tree. Could maybe be mitigated with a good set of helpers (e.g. to flatten the tree).
• The backend could get a simplified (flattened?) scene. This requires us to maintain two separate scene APIs (one for the compositors, one for the backends).
• The per-backend logic could live inside the scene implementation entirely. This isn't great because this makes it impossible to have out-of-tree backends taking advantage of it.

[emersion]

Minimal API draft:

enum wlr_scene_node_type {
	WLR_SCENE_NODE_ROOT,
	WLR_SCENE_NODE_TREE,
	WLR_SCENE_NODE_SURFACE,
	WLR_SCENE_NODE_OUTPUT,
};

struct wlr_scene_node_state {
	struct wl_list children; // wlr_scene_node_state.link
	struct wl_list link; // wlr_scene_node_state.children
	bool enabled;
	int x, y;
};

struct wlr_scene_node {
	enum wlr_scene_node_type type;
	struct wlr_scene_node *parent;
	struct wlr_scene_node_state current, pending;
};

struct wlr_scene {
	struct wlr_scene_node node;
};

struct wlr_scene_tree {
	struct wlr_scene_node node;
};

struct wlr_scene_surface {
	struct wlr_scene_node node;
	struct wlr_surface *surface;
};

struct wlr_scene_output {
	struct wlr_scene_node node;
	struct wlr_output *output;
};

struct wlr_scene *wlr_scene_create(void);
void wlr_scene_destroy(struct wlr_scene *scene);

void wlr_scene_node_destroy(struct wlr_scene_node *node);
void wlr_scene_node_commit(struct wlr_scene_node *node);
void wlr_scene_node_toggle(struct wlr_scene_node *node, bool enabled);
void wlr_scene_node_move(struct wlr_scene_node *node, int x, int y);
void wlr_scene_node_place_above(struct wlr_scene_node *node,
	struct wlr_scene_node *ref);
void wlr_scene_node_place_below(struct wlr_scene_node *node,
	struct wlr_scene_node *ref);

struct wlr_scene_tree *wlr_scene_tree_create(struct wlr_scene_node *parent);

struct wlr_scene_surface *wlr_scene_surface_create(struct wlr_scene_node *parent,
	struct wlr_surface *surface);

struct wlr_scene_output *wlr_scene_output_create(struct wlr_scene *scene);

[ddevault]

Seems like a good start.

[ascent12]

The backend could get a simplified (flattened?) scene. This requires us to maintain two separate scene APIs (one for the compositors, one for the backends).

I don't think it's that bad if the backend has its own separate scene API. They are sufficiently different enough.

• Backend is per-output, compositor's is the entire layout space
• Backend is in output buffer coordinates with no global transforms (but does have per-view transforms), compositor is in layout coordinates
• Backend can just be a flat list/array, because we don't care about the ergonomics of changing anything. I'd expect that a user would recreate this every frame from their other scene graph.

It would be nice to keep any complexity about the layout and global transforms outside of the backend. We can keep everything as close as it can possibly be to the values that libliftoff and KMS wants to see.

[emersion]

I'd expect that a user would recreate this every frame from their other scene graph.

Hmm, actually libliftoff cares a lot about keeping the same scenegraph objects because it needs to track which surfaces are updated frequently to put these in planes before others.

[ascent12]

Well, if persistent state helps, that's fine. It's slightly more complexity for the compositor scene graph, but not that much.

[emersion]

The basic API has landed in #1966, and various PRs have been adding functionality. Let's close this issue and create new dedicated issues for missing features.