voidsurface_t::attach(buffer_tconst&buffer,int32_tx,int32_ty)
set the surface contents
Parametersbuffer buffer of surface contents
x surface-local x coordinate
y surface-local y coordinate
Set a buffer as the content of this surface.
The new size of the surface is calculated based on the buffer size transformed by the inverse
buffer_transform and the inverse buffer_scale. This means that at commit time the supplied buffer size
must be an integer multiple of the buffer_scale. If that's not the case, an invalid_size error is sent.
The x and y arguments specify the location of the new pending buffer's upper left corner, relative to the
current buffer's upper left corner, in surface-local coordinates. In other words, the x and y, combined
with the new surface size define in which directions the surface's size changes. Setting anything other
than 0 as x and y arguments is discouraged, and should instead be replaced with using the separate
wl_surface.offset request.
When the bound wl_surface version is 5 or higher, passing any non-zero x or y is a protocol violation,
and will result in an 'invalid_offset' error being raised. To achieve equivalent semantics, use
wl_surface.offset.
Surface contents are double-buffered state, see wl_surface.commit.
The initial surface contents are void; there is no content. wl_surface.attach assigns the given wl_buffer
as the pending wl_buffer. wl_surface.commit makes the pending wl_buffer the new surface contents, and the
size of the surface becomes the size calculated from the wl_buffer, as described above. After commit,
there is no pending buffer until the next attach.
Committing a pending wl_buffer allows the compositor to read the pixels in the wl_buffer. The compositor
may access the pixels at any time after the wl_surface.commit request. When the compositor will not
access the pixels anymore, it will send the wl_buffer.release event. Only after receiving
wl_buffer.release, the client may reuse the wl_buffer. A wl_buffer that has been attached and then
replaced by another attach instead of committed will not receive a release event, and is not used by the
compositor.
If a pending wl_buffer has been committed to more than one wl_surface, the delivery of wl_buffer.release
events becomes undefined. A well behaved client should not rely on wl_buffer.release events in this case.
Alternatively, a client could create multiple wl_buffer objects from the same backing storage or use
wp_linux_buffer_release.
Destroying the wl_buffer after wl_buffer.release does not change the surface contents. Destroying the
wl_buffer before wl_buffer.release is allowed as long as the underlying buffer storage isn't re-used
(this can happen e.g. on client process termination). However, if the client destroys the wl_buffer
before receiving the wl_buffer.release event and mutates the underlying buffer storage, the surface
contents become undefined immediately.
If wl_surface.attach is sent with a NULL wl_buffer, the following wl_surface.commit will remove the
surface content.
Examplesegl.cpp, and shm.cpp.
Definition at line 2693 of file wayland-client-protocol.cpp.
wl_proxy*wayland::proxy_t::c_ptr()const[inherited]
Get a pointer to the underlying C struct.
Returns
The underlying wl_proxy wrapped by this proxy_t if it exists, otherwise an exception is thrown
boolsurface_t::can_damage_buffer()const
Check whether the damage_buffer function is available with the currently bound version of the protocol.
Definition at line 2757 of file wayland-client-protocol.cpp.
boolsurface_t::can_offset()const
Check whether the offset function is available with the currently bound version of the protocol.
Definition at line 2768 of file wayland-client-protocol.cpp.
boolsurface_t::can_set_buffer_scale()const
Check whether the set_buffer_scale function is available with the currently bound version of the
protocol.
Definition at line 2746 of file wayland-client-protocol.cpp.
boolsurface_t::can_set_buffer_transform()const
Check whether the set_buffer_transform function is available with the currently bound version of the
protocol.
Definition at line 2735 of file wayland-client-protocol.cpp.
voidsurface_t::commit()
commit pending surface state Surface state (input, opaque, and damage regions, attached buffers, etc.) is
double-buffered. Protocol requests modify the pending state, as opposed to the current state in use by
the compositor. A commit request atomically applies all pending state, replacing the current state. After
commit, the new pending state is as documented for each related request.
On commit, a pending wl_buffer is applied first, and all other state second. This means that all
coordinates in double-buffered state are relative to the new wl_buffer coming into use, except for
wl_surface.attach itself. If there is no pending wl_buffer, the coordinates are relative to the current
surface contents.
All requests that need a commit to become effective are documented to affect double-buffered state.
Other interfaces may add further double-buffered surface state.
Examplesegl.cpp, and shm.cpp.
Definition at line 2724 of file wayland-client-protocol.cpp.
voidsurface_t::damage(int32_tx,int32_ty,int32_twidth,int32_theight)
mark part of the surface damaged
Parametersx surface-local x coordinate
y surface-local y coordinate
width width of damage rectangle
height height of damage rectangle
This request is used to describe the regions where the pending buffer is different from the current
surface contents, and where the surface therefore needs to be repainted. The compositor ignores the parts
of the damage that fall outside of the surface.
Damage is double-buffered state, see wl_surface.commit.
The damage rectangle is specified in surface-local coordinates, where x and y specify the upper left
corner of the damage rectangle.
The initial value for pending damage is empty: no damage. wl_surface.damage adds pending damage: the new
pending damage is the union of old pending damage and the given rectangle.
wl_surface.commit assigns pending damage as the current damage, and clears pending damage. The server
will clear the current damage as it repaints the surface.
Note! New clients should not use this request. Instead damage can be posted with wl_surface.damage_buffer
which uses buffer coordinates instead of surface coordinates.
Examplesegl.cpp, and shm.cpp.
Definition at line 2699 of file wayland-client-protocol.cpp.
voidsurface_t::damage_buffer(int32_tx,int32_ty,int32_twidth,int32_theight)
mark part of the surface damaged using buffer coordinates
Parametersx buffer-local x coordinate
y buffer-local y coordinate
width width of damage rectangle
height height of damage rectangle
This request is used to describe the regions where the pending buffer is different from the current
surface contents, and where the surface therefore needs to be repainted. The compositor ignores the parts
of the damage that fall outside of the surface.
Damage is double-buffered state, see wl_surface.commit.
The damage rectangle is specified in buffer coordinates, where x and y specify the upper left corner of
the damage rectangle.
The initial value for pending damage is empty: no damage. wl_surface.damage_buffer adds pending damage:
the new pending damage is the union of old pending damage and the given rectangle.
wl_surface.commit assigns pending damage as the current damage, and clears pending damage. The server
will clear the current damage as it repaints the surface.
This request differs from wl_surface.damage in only one way - it takes damage in buffer coordinates
instead of surface-local coordinates. While this generally is more intuitive than surface coordinates, it
is especially desirable when using wp_viewport or when a drawing library (like EGL) is unaware of buffer
scale and buffer transform.
Note: Because buffer transformation changes and damage requests may be interleaved in the protocol
stream, it is impossible to determine the actual mapping between surface and buffer damage until
wl_surface.commit time. Therefore, compositors wishing to take both kinds of damage into account will
have to accumulate damage from the two requests separately and only transform from one to the other after
receiving the wl_surface.commit.
Definition at line 2752 of file wayland-client-protocol.cpp.
callback_tsurface_t::frame()
request a frame throttling hint
Returns
callback object for the frame request
Request a notification when it is a good time to start drawing a new frame, by creating a frame callback.
This is useful for throttling redrawing operations, and driving animations.
When a client is animating on a wl_surface, it can use the 'frame' request to get notified when it is a
good time to draw and commit the next frame of animation. If the client commits an update earlier than
that, it is likely that some updates will not make it to the display, and the client is wasting resources
by drawing too often.
The frame request will take effect on the next wl_surface.commit. The notification will only be posted
for one frame unless requested again. For a wl_surface, the notifications are posted in the order the
frame requests were committed.
The server must send the notifications so that a client will not send excessive updates, while still
allowing the highest possible update rate for clients that wait for the reply before drawing again. The
server should give some time for the client to draw and commit after sending the frame callback events to
let it hit the next output refresh.
A server should avoid signaling the frame callbacks if the surface is not visible in any way, e.g. the
surface is off-screen, or completely obscured by other opaque surfaces.
The object returned by this request will be destroyed by the compositor after the callback is fired and
as such the client must not attempt to use it after that point.
The callback_data passed in the callback is the current time, in milliseconds, with an undefined base.
Examplesegl.cpp, and shm.cpp.
Definition at line 2705 of file wayland-client-protocol.cpp.
std::stringwayland::proxy_t::get_class()const[inherited]
Get the interface name (class) of a proxy object.
Returns
The interface name of the object associated with the proxy
uint32_twayland::proxy_t::get_id()const[inherited]
Get the id of a proxy object.
Returns
The id the object associated with the proxy
uint32_twayland::proxy_t::get_version()const[inherited]
Get the protocol object version of a proxy object. Gets the protocol object version of a proxy object, or
0 if the proxy was created with unversioned API.
A returned value of 0 means that no version information is available, so the caller must make safe
assumptions about the object's real version.
display_t will always return version 0.
Returns
The protocol object version of the proxy or 0
wrapper_typewayland::proxy_t::get_wrapper_type()const[inline],[inherited]
Get the type of a proxy object.
Definition at line 302 of file wayland-client.hpp.
voidsurface_t::offset(int32_tx,int32_ty)
set the surface contents offset
Parametersx surface-local x coordinate
y surface-local y coordinate
The x and y arguments specify the location of the new pending buffer's upper left corner, relative to the
current buffer's upper left corner, in surface-local coordinates. In other words, the x and y, combined
with the new surface size define in which directions the surface's size changes.
Surface location offset is double-buffered state, see wl_surface.commit.
This request is semantically equivalent to and the replaces the x and y arguments in the
wl_surface.attach request in wl_surface versions prior to 5. See wl_surface.attach for details.
Definition at line 2763 of file wayland-client-protocol.cpp.
std::function<void(output_t)>&surface_t::on_enter()
surface enters an output
Parametersoutput output entered by the surface
This is emitted whenever a surface's creation, movement, or resizing results in some part of it being
within the scanout region of an output.
Note that a surface may be overlapping with zero or more outputs.
Definition at line 2774 of file wayland-client-protocol.cpp.
std::function<void(output_t)>&surface_t::on_leave()
surface leaves an output
Parametersoutput output left by the surface
This is emitted whenever a surface's creation, movement, or resizing results in it no longer having any
part of it within the scanout region of an output.
Clients should not use the number of outputs the surface is on for frame throttling purposes. The surface
might be hidden even if no leave event has been sent, and the compositor might expect new surface content
updates even if no enter event has been sent. The frame event should be used instead.
Definition at line 2779 of file wayland-client-protocol.cpp.
wayland::proxy_t::operatorbool()const[inherited]
Check whether this wrapper actually wraps an object.
Returns
true if there is an underlying object, false if this wrapper is empty
boolwayland::proxy_t::operator!=(constproxy_t&right)const[inherited]
Check whether two wrappers refer to different objects.
boolwayland::proxy_t::operator==(constproxy_t&right)const[inherited]
Check whether two wrappers refer to the same object.
boolwayland::proxy_t::proxy_has_object()const[inherited]
Check whether this wrapper actually wraps an object.
Returns
true if there is an underlying object, false if this wrapper is empty
voidwayland::proxy_t::proxy_release()[inherited]
Release the wrapped object (if any), making this an empty wrapper. Note that display_t instances cannot
be released this way. Attempts to do so are ignored.
Examplesforeign_display.cpp.
voidsurface_t::set_buffer_scale(int32_tscale)
sets the buffer scaling factor
Parametersscale positive scale for interpreting buffer contents
This request sets an optional scaling factor on how the compositor interprets the contents of the buffer
attached to the window.
Buffer scale is double-buffered state, see wl_surface.commit.
A newly created surface has its buffer scale set to 1.
wl_surface.set_buffer_scale changes the pending buffer scale. wl_surface.commit copies the pending buffer
scale to the current one. Otherwise, the pending and current values are never changed.
The purpose of this request is to allow clients to supply higher resolution buffer data for use on high
resolution outputs. It is intended that you pick the same buffer scale as the scale of the output that
the surface is displayed on. This means the compositor can avoid scaling when rendering the surface on
that output.
Note that if the scale is larger than 1, then you have to attach a buffer that is larger (by a factor of
scale in each dimension) than the desired surface size.
If scale is not positive the invalid_scale protocol error is raised.
Definition at line 2741 of file wayland-client-protocol.cpp.
voidsurface_t::set_buffer_transform(output_transformconst&transform)
sets the buffer transformation
Parameterstransform transform for interpreting buffer contents
This request sets an optional transformation on how the compositor interprets the contents of the buffer
attached to the surface. The accepted values for the transform parameter are the values for
wl_output.transform.
Buffer transform is double-buffered state, see wl_surface.commit.
A newly created surface has its buffer transformation set to normal.
wl_surface.set_buffer_transform changes the pending buffer transformation. wl_surface.commit copies the
pending buffer transformation to the current one. Otherwise, the pending and current values are never
changed.
The purpose of this request is to allow clients to render content according to the output transform, thus
permitting the compositor to use certain optimizations even if the display is rotated. Using hardware
overlays and scanning out a client buffer for fullscreen surfaces are examples of such optimizations.
Those optimizations are highly dependent on the compositor implementation, so the use of this request
should be considered on a case-by-case basis.
Note that if the transform value includes 90 or 270 degree rotation, the width of the buffer will become
the surface height and the height of the buffer will become the surface width.
If transform is not one of the values from the wl_output.transform enum the invalid_transform protocol
error is raised.
Definition at line 2730 of file wayland-client-protocol.cpp.
voidsurface_t::set_input_region(region_tconst®ion)
set input region
Parametersregion input region of the surface
This request sets the region of the surface that can receive pointer and touch events.
Input events happening outside of this region will try the next surface in the server surface stack. The
compositor ignores the parts of the input region that fall outside of the surface.
The input region is specified in surface-local coordinates.
Input region is double-buffered state, see wl_surface.commit.
wl_surface.set_input_region changes the pending input region. wl_surface.commit copies the pending region
to the current region. Otherwise the pending and current regions are never changed, except cursor and
icon surfaces are special cases, see wl_pointer.set_cursor and wl_data_device.start_drag.
The initial value for an input region is infinite. That means the whole surface will accept input.
Setting the pending input region has copy semantics, and the wl_region object can be destroyed
immediately. A NULL wl_region causes the input region to be set to infinite.
Definition at line 2718 of file wayland-client-protocol.cpp.
voidsurface_t::set_opaque_region(region_tconst®ion)
set opaque region
Parametersregion opaque region of the surface
This request sets the region of the surface that contains opaque content.
The opaque region is an optimization hint for the compositor that lets it optimize the redrawing of
content behind opaque regions. Setting an opaque region is not required for correct behaviour, but
marking transparent content as opaque will result in repaint artifacts.
The opaque region is specified in surface-local coordinates.
The compositor ignores the parts of the opaque region that fall outside of the surface.
Opaque region is double-buffered state, see wl_surface.commit.
wl_surface.set_opaque_region changes the pending opaque region. wl_surface.commit copies the pending
region to the current region. Otherwise, the pending and current regions are never changed.
The initial value for an opaque region is empty. Setting the pending opaque region has copy semantics,
and the wl_region object can be destroyed immediately. A NULL wl_region causes the pending opaque region
to be set to empty.
Definition at line 2712 of file wayland-client-protocol.cpp.
voidwayland::proxy_t::set_queue(event_queue_tqueue)[inherited]
Assign a proxy to an event queue.
Parametersqueue The event queue that will handle this proxy
Assign proxy to event queue. Events coming from proxy will be queued in queue instead of the display's
main queue.
See also: display_t::dispatch_queue().
Examplesproxy_wrapper.cpp.
Install Now
PNG Icons
