NAME

       wl_shm_buffer - A SHM buffer.

SYNOPSIS

   Public Member Functions
       void * wl_shm_buffer_get_data (struct wl_shm_buffer *buffer)
       struct wl_shm_pool * wl_shm_buffer_ref_pool (struct wl_shm_buffer *buffer)
       void wl_shm_buffer_begin_access (struct wl_shm_buffer *buffer)
       void wl_shm_buffer_end_access (struct wl_shm_buffer *buffer)

   Data Fields
       struct wl_resource * resource
       int32_t width
       int32_t height
       int32_t stride
       uint32_t format
       int offset
       struct wl_shm_pool * pool

Detailed Description

       A SHM buffer.

       wl_shm_buffer provides a helper for accessing the contents of a wl_buffer resource created
       via the wl_shm interface.

       A wl_shm_buffer becomes invalid as soon as its wl_resource is destroyed.

Member Function Documentation

   void wl_shm_buffer_begin_access (struct wl_shm_buffer * buffer)
       Mark that the given SHM buffer is about to be accessed

       Parameters
           buffer The SHM buffer

       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 wl_shm_buffer_end_access 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 wl_shm_buffer_end_access 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 wl_shm_buffer_begin_access. These functions are thread-safe and it is allowed to
       simultaneously access different buffers or the same buffer from multiple threads.

   void wl_shm_buffer_end_access (struct wl_shm_buffer * buffer)
       Ends the access to a buffer started by wl_shm_buffer_begin_access

       Parameters
           buffer The SHM buffer

       This should be called after wl_shm_buffer_begin_access 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.

   void * wl_shm_buffer_get_data (struct wl_shm_buffer * buffer)
       Get a pointer to the memory for the SHM buffer

       Parameters
           buffer The buffer object

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

       As this buffer is memory-mapped, reading from it 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.

   struct wl_shm_pool * wl_shm_buffer_ref_pool (struct wl_shm_buffer * buffer)
       Get a reference to a shm_buffer's shm_pool

       Parameters
           buffer The buffer object

       Returns a pointer to a buffer's shm_pool and increases the shm_pool refcount.

       The compositor must remember to call wl_shm_pool_unref when it no longer needs the
       reference to ensure proper destruction of the pool.

       See also
           wl_shm_pool_unref

Field Documentation

   uint32_t wl_shm_buffer::format
   int32_t wl_shm_buffer::height
   int wl_shm_buffer::offset
   struct wl_shm_pool* wl_shm_buffer::pool
   struct wl_resource* wl_shm_buffer::resource
   int32_t wl_shm_buffer::stride
   int32_t wl_shm_buffer::width

Author

       Generated automatically by Doxygen for Wayland from the source code.