Stride constraints for wl_shm_pool::create_buffer
The current text for wl_shm_pool::create_buffer
defines the image stride as follows:
The stride argument specifies the number of bytes from the beginning of one row to the beginning of the next.
wl_shm
also has an invalid stride error, with name="invalid_stride", summary="invalid size or stride during pool or buffer creation".
However, it is not specified what stride values are invalid. To ensure that applications can rely on the same behavior across compositors, this should be standardized and documented.
In theory, we could allow any stride value, as long as the union of the content bytes of the image lies within the shm pool region. By the definition of the stride quoted above, if the first row of the image starts at address p
, then the second row of the image starts at p + stride
. This is well defined even if the stride is zero, negative, or smaller in absolute value than width * bpp
-- although not necessarily useful.
Some common constraints in practice:
- libwayland-shm requires the stride (in bytes) to be at least the image width (in pixels)
- wlroots/wlr-shm currently requires that the stride to be a multiple of
bpp
, the number of bytes for a pixel - pixman (and cairo) require that the stride be a multiple of 4.
- libwayland-shm requires that the image row padding also fits in the pool; i.e.,
offset+stride*height<pool_size
, which can be more than necessary if, say,height=1
andstride > width*bpp
See also #333 for related issues specifying multi-planar and subsampled formats.