summaryrefslogtreecommitdiffstats
path: root/libmpv/render.h
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2020-09-17 15:25:49 +0200
committerwm4 <wm4@nowhere>2020-09-17 15:25:49 +0200
commit76fb001c4208bcb9d235d2e8e920f419ad844dd5 (patch)
treeaebfc6f26fc12e8b46286ed37eccc3468b291c3e /libmpv/render.h
parent083adf97e14f3996f3c5c54b418de9cc5905b027 (diff)
downloadmpv-76fb001c4208bcb9d235d2e8e920f419ad844dd5.tar.bz2
mpv-76fb001c4208bcb9d235d2e8e920f419ad844dd5.tar.xz
client API: update alignment requirements for software rendering
Previous commit fixes it for libswscale. The libzimg path has extra code to copy by slice, but it still may access pixel groups using normal memory accesses (for example, reading rgba pixel data via uint32_t), so document a minimum alignment requirement per pixel format.
Diffstat (limited to 'libmpv/render.h')
-rw-r--r--libmpv/render.h21
1 files changed, 12 insertions, 9 deletions
diff --git a/libmpv/render.h b/libmpv/render.h
index ead462cbb6..06811d546c 100644
--- a/libmpv/render.h
+++ b/libmpv/render.h
@@ -370,9 +370,11 @@ typedef enum mpv_render_param_type {
* address 0), the "0" component contains uninitialized garbage (often
* the value 0, but not necessarily; the bad naming is inherited from
* FFmpeg)
+ * Pixel alignment size: 4 bytes
* "rgb24"
* 3 bytes per pixel RGB. This is strongly discouraged because it is
* very slow.
+ * Pixel alignment size: 1 bytes
* other
* The API may accept other pixel formats, using mpv internal format
* names, as long as it's internally marked as RGB, has exactly 1
@@ -390,13 +392,15 @@ typedef enum mpv_render_param_type {
* target surface. It must be a multiple of the pixel size, and have space
* for the surface width as specified by MPV_RENDER_PARAM_SW_SIZE.
*
- * It should be a multiple of 64 to facilitate fast SIMD operation. Lower
- * alignment might trigger slower code paths. In addition, it appears that
- * if libswscale is used, stride must be at least a multiple of 16, or
- * libswscale may randomly corrupt memory. The API still accepts unaligned
- * values, because libswscale is not supposed to corrupt memory, and whether
- * it does depends on its implementation details and bugs. If mpv is built
- * with zimg (and zimg is not disabled), no problems should occur.
+ * Both stride and pointer value should be a multiple of 64 to facilitate
+ * fast SIMD operation. Lower alignment might trigger slower code paths,
+ * and in the worst case, will copy the entire target frame. If mpv is built
+ * with zimg (and zimg is not disabled), the performance impact might be
+ * less.
+ * In either cases, the pointer and stride must be aligned at least to the
+ * pixel alignment size. Otherwise, crashes and undefined behavior is
+ * possible on platforms which do not support unaligned accesses (either
+ * through normal memory access or aligned SIMD memory access instructions).
*/
MPV_RENDER_PARAM_SW_STRIDE = 19,
/*
@@ -414,8 +418,7 @@ typedef enum mpv_render_param_type {
* line (starting at bytepos(w, h) until (pointer + stride * h)) is
* writable.
*
- * It should be a aligned to 64 to facilitate fast SIMD operation. Lower
- * alignment might trigger slower code paths.
+ * See MPV_RENDER_PARAM_SW_STRIDE for alignment requirements.
*/
MPV_RENDER_PARAM_SW_POINTER = 20,
} mpv_render_param_type;