Package org.freedesktop.wayland.server

Class ShmBuffer

java.lang.Object

org.freedesktop.wayland.server.ShmBuffer

public class ShmBuffer
extends Object

Field Summary

Fields

Modifier and Type	Field	Description
final MemorySegment	pointer

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ShmBuffer(MemorySegment pointer)
	ShmBuffer(Client client, int id, int width, int height, int stride, int format)	Create a new underlying WlBufferResource with the constructed ShmBuffer as it's implementation.

Method Summary

Modifier and Type	Method	Description
void	beginAccess()	Mark that the given SHM buffer is about to be accessed
void	endAccess()	Ends the access to a buffer started by beginAccess().
boolean	equals(Object o)
static ShmBuffer	get(Resource<?> resource)
ByteBuffer	getData()	Get a pointer to the memory for the SHM buffer
int	getFormat()
int	getHeight()
int	getStride()
int	getWidth()
int	hashCode()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

pointer

public final MemorySegment pointer

Constructor Details

ShmBuffer

public ShmBuffer(Client client,
 int id,
 int width,
 int height,
 int stride,
 int format)

Create a new underlying WlBufferResource with the constructed ShmBuffer as it's implementation.

ShmBuffer should never be stored in a compositor instead it should always be queried from a WlBufferResource. Listening for the resource's destruction can be done when the buffer resource is attached to a surface.

Parameters:

client -

id -

width -

height -

stride -

format -

ShmBuffer

protected ShmBuffer(MemorySegment pointer)

Method Details

get

public static ShmBuffer get(Resource<?> resource)

beginAccess

public void beginAccess()

Mark that the given SHM buffer is about to be accessed

An SHM buffer is a memory-mapped file given by the client. According to POSIX, reading from a memory-mapped region that extends off the end of the file will cause a SIGBUS signal to be generated. Normally this would cause the compositor to terminate. In order to make the compositor robust against clients that change the size of the underlying file or lie about its size, you should protect access to the buffer by calling this function before reading from the memory and call endAccess() afterwards. This will install a signal handler for SIGBUS which will prevent the compositor from crashing.

After calling this function the signal handler will remain installed for the lifetime of the compositor process. Note that this function will not work properly if the compositor is also installing its own handler for SIGBUS.

If a SIGBUS signal is received for an address within the range of the SHM pool of the given buffer then the client will be sent an error event when endAccess() is called. If the signal is for an address outside that range then the signal handler will reraise the signal which would will likely cause the compositor to terminate.

It is safe to nest calls to these functions as long as the nested calls are all accessing the same buffer. The number of calls to wl_shm_buffer_end_access must match the number of calls to beginAccess(). These functions are thread-safe and it is allowed to simultaneously access different buffers or the same buffer from multiple threads.

endAccess

public void endAccess()

Ends the access to a buffer started by beginAccess().

This should be called after beginAccess() once the buffer is no longer being accessed. If a SIGBUS signal was generated in-between these two calls then the resource for the given buffer will be sent an error.

getData

public ByteBuffer getData()

Get a pointer to the memory for the SHM buffer

Returns a pointer which can be used to read the data contained in the given SHM buffer.

As this buffer is memory-mapped, reading it from may generate SIGBUS signals. This can happen if the client claims that the buffer is larger than it is or if something truncates the underlying file. To prevent this signal from causing the compositor to crash you should call wl_shm_buffer_begin_access and wl_shm_buffer_end_access around code that reads from the memory.

Returns:

a direct ByteBuffer.

getHeight

public int getHeight()

getStride

public int getStride()

getFormat

public int getFormat()

getWidth

public int getWidth()

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object