Twclient quick reference¶
Client data structures¶
tw_globals : the global structure that fits the need of an wayland client. It contains things like
wl_shm
,wl_shm_format
,wl_compositor
,wl_display
.Inputs: We only have one input per client, this would be connect to one seat, input will handle
tw_event_queue : introduced originally for
tw_shell
to handle system generated events like time lapse and wayland protocol events. Very much likewl_event_loop
, which is not available in clients.tw_event : this leads to another interface for use to create its own event and watch the event. It didn’t go as far as the
wl_protocols
where you create custom protocols and have handlers for them.
tw_shm_pool : the allocator for shared buffers, binds to
wl_buffer
.
UIs¶
tw_appsurf : it binds to an
wl_surface
for different roles(protocols). The surface has it implementation of buffer and input events, it has the data but no actual methods to interact with it.tw_appsurf
was first created for distinguishing background surface and panel surface. So in a sense, Right now it is used for any kind of single surface app. Note that:As an
tw_appsurf
, it has it’s own<x,y,w,h>
values.It also has input-events, to generate the a new frame.
tw_appsurf
is designed to work with different proxies,taiwins_ui
(this is taiwins specific, drawn in UI layer),wl_shell_surface
orxdg_shell_surface
should all work, it is an wrap aroundwl_surface
and provides convenient methods for commiting surface and do a new frame.tw_appsurf_event_filter
. But you know not everyting relates to a surface is about frame, would it be able to update something without drawing a new frame? This is why we have an event filter, you can instal the filter to a surface, it runs before thetw_appsurf.frame
and it can optionally skip theframe
.
Example of UI implementation¶
You can implement a tw_appsurf
for your needs using *_impl_app_surf
, there are already predefined implementatin you can take advantage of.
background: background is picture reading and posting, it could be implemented as animation, by calling a frame.
nuklear_backend: this GUI library is implemented with OpenGL or cairo, it implements a
tw_appsurf
like a sub class, then use it users can use simplytw_appsurf
to operate.embeded_surface: This is one that complicates the implementation. It does not have its own data, but also need a frame. The frame is triggered by events.
frame vs other event.¶
Right now tw_appsurf
has a central frame
callback to deal with all events, check out tw_event
structure for what is available, note that those are the common events. You may implement your specific event through tw_event_queue
.
If you do animations, in wayland, you need to call the commit
plus a frame
in the next done event. tw_appsurf
already has tw_appsurf_request_frame
to request a draw call. Optionally, when you call tw_appsurf_frame
, you can specify it is animated.
NUKLEAR backend using Wayland¶
We implement a cairo and EGL based nuklear renderer for tw_appsurf
, user can invoke nk_egl(cairo)_impl_appsurf
to setup tw_appsurf
to work with nuklear
. Then you would be able to use all the nuklear functions in the frame callback.
NUKLEAR pipeline¶
The nuklear backend does all the heavy job of implementing all the ui forms that we need for GUI code and you can implement different backend for it. Backend implementation boils down to take draw command from nk_command
and draw basic geometry, text and image.
functions like
nk_label
,nk_row
translate intonk_command
though functions likenk_draw_text
,nk_draw_image
.if you decide to write a CPU backend, then you have to draw based on those command, uses for example (Cairo), remember to use the double buffer(required for wayland).
if you use GPU backend, there is an additional helper function called
nk_convert
, which converts the command into vertex buffer, element based on layout you specified.
New Font and image¶
nk_wl_*_backend
implements a resource management, to load font and image, call nk_wl_load_image
and nk_wl_new_font
name conversion¶
when using create
and destroy
, for exemple, wl_shm_pool_create
and wl_shm_pool_destroy
, we are getting a pointer then free the pointer in the end.
The struct
is usually not visible, declared in header, defined in source code. Good example is nk_egl_backend
, since there could be only one implementation of it.
In this case, user has the control over the memory, but the interface controls the heap if any, after calling end
, the struct should returns to the init state.
Same as above.