1 /* 2 * This an unstable interface of wlroots. No guarantees are made regarding the 3 * future consistency of this API. 4 */ 5 #ifndef WLR_USE_UNSTABLE 6 #error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features" 7 #endif 8 9 #ifndef WLR_TYPES_WLR_OUTPUT_H 10 #define WLR_TYPES_WLR_OUTPUT_H 11 12 #include <pixman.h> 13 #include <stdbool.h> 14 #include <time.h> 15 #include <wayland-server-protocol.h> 16 #include <wayland-util.h> 17 #include <wlr/render/dmabuf.h> 18 #include <wlr/types/wlr_buffer.h> 19 20 struct wlr_output_mode { 21 int32_t width, height; 22 int32_t refresh; // mHz 23 bool preferred; 24 struct wl_list link; 25 }; 26 27 struct wlr_output_cursor { 28 struct wlr_output *output; 29 double x, y; 30 bool enabled; 31 bool visible; 32 uint32_t width, height; 33 int32_t hotspot_x, hotspot_y; 34 struct wl_list link; 35 36 // only when using a software cursor without a surface 37 struct wlr_texture *texture; 38 39 // only when using a cursor surface 40 struct wlr_surface *surface; 41 struct wl_listener surface_commit; 42 struct wl_listener surface_destroy; 43 44 struct { 45 struct wl_signal destroy; 46 } events; 47 }; 48 49 enum wlr_output_adaptive_sync_status { 50 WLR_OUTPUT_ADAPTIVE_SYNC_DISABLED, 51 WLR_OUTPUT_ADAPTIVE_SYNC_ENABLED, 52 WLR_OUTPUT_ADAPTIVE_SYNC_UNKNOWN, // requested, but maybe disabled 53 }; 54 55 enum wlr_output_state_field { 56 WLR_OUTPUT_STATE_BUFFER = 1 << 0, 57 WLR_OUTPUT_STATE_DAMAGE = 1 << 1, 58 WLR_OUTPUT_STATE_MODE = 1 << 2, 59 WLR_OUTPUT_STATE_ENABLED = 1 << 3, 60 WLR_OUTPUT_STATE_SCALE = 1 << 4, 61 WLR_OUTPUT_STATE_TRANSFORM = 1 << 5, 62 WLR_OUTPUT_STATE_ADAPTIVE_SYNC_ENABLED = 1 << 6, 63 WLR_OUTPUT_STATE_GAMMA_LUT = 1 << 7, 64 }; 65 66 enum wlr_output_state_buffer_type { 67 WLR_OUTPUT_STATE_BUFFER_RENDER, 68 WLR_OUTPUT_STATE_BUFFER_SCANOUT, 69 }; 70 71 enum wlr_output_state_mode_type { 72 WLR_OUTPUT_STATE_MODE_FIXED, 73 WLR_OUTPUT_STATE_MODE_CUSTOM, 74 }; 75 76 /** 77 * Holds the double-buffered output state. 78 */ 79 struct wlr_output_state { 80 uint32_t committed; // enum wlr_output_state_field 81 pixman_region32_t damage; // output-buffer-local coordinates 82 bool enabled; 83 float scale; 84 enum wl_output_transform transform; 85 bool adaptive_sync_enabled; 86 87 // only valid if WLR_OUTPUT_STATE_BUFFER 88 enum wlr_output_state_buffer_type buffer_type; 89 struct wlr_buffer *buffer; // if WLR_OUTPUT_STATE_BUFFER_SCANOUT 90 91 // only valid if WLR_OUTPUT_STATE_MODE 92 enum wlr_output_state_mode_type mode_type; 93 struct wlr_output_mode *mode; 94 struct { 95 int32_t width, height; 96 int32_t refresh; // mHz, may be zero 97 } custom_mode; 98 99 // only valid if WLR_OUTPUT_STATE_GAMMA_LUT 100 uint16_t *gamma_lut; 101 size_t gamma_lut_size; 102 }; 103 104 struct wlr_output_impl; 105 106 /** 107 * A compositor output region. This typically corresponds to a monitor that 108 * displays part of the compositor space. 109 * 110 * The `frame` event will be emitted when it is a good time for the compositor 111 * to submit a new frame. 112 * 113 * To render a new frame, compositors should call `wlr_output_attach_render`, 114 * render and call `wlr_output_commit`. No rendering should happen outside a 115 * `frame` event handler or before `wlr_output_attach_render`. 116 */ 117 struct wlr_output { 118 const struct wlr_output_impl *impl; 119 struct wlr_backend *backend; 120 struct wl_display *display; 121 122 struct wl_global *global; 123 struct wl_list resources; 124 125 char name[24]; 126 char *description; // may be NULL 127 char make[56]; 128 char model[16]; 129 char serial[16]; 130 int32_t phys_width, phys_height; // mm 131 132 // Note: some backends may have zero modes 133 struct wl_list modes; // wlr_output_mode::link 134 struct wlr_output_mode *current_mode; 135 int32_t width, height; 136 int32_t refresh; // mHz, may be zero 137 138 bool enabled; 139 float scale; 140 enum wl_output_subpixel subpixel; 141 enum wl_output_transform transform; 142 enum wlr_output_adaptive_sync_status adaptive_sync_status; 143 144 bool needs_frame; 145 // damage for cursors and fullscreen surface, in output-local coordinates 146 bool frame_pending; 147 float transform_matrix[9]; 148 149 struct wlr_output_state pending; 150 151 // Commit sequence number. Incremented on each commit, may overflow. 152 uint32_t commit_seq; 153 154 struct { 155 // Request to render a frame 156 struct wl_signal frame; 157 // Emitted when software cursors or backend-specific logic damage the 158 // output 159 struct wl_signal damage; // wlr_output_event_damage 160 // Emitted when a new frame needs to be committed (because of 161 // backend-specific logic) 162 struct wl_signal needs_frame; 163 // Emitted right before commit 164 struct wl_signal precommit; // wlr_output_event_precommit 165 // Emitted right after commit 166 struct wl_signal commit; // wlr_output_event_commit 167 // Emitted right after the buffer has been presented to the user 168 struct wl_signal present; // wlr_output_event_present 169 struct wl_signal enable; 170 struct wl_signal mode; 171 struct wl_signal scale; 172 struct wl_signal transform; 173 struct wl_signal description; 174 struct wl_signal destroy; 175 } events; 176 177 struct wl_event_source *idle_frame; 178 struct wl_event_source *idle_done; 179 180 int attach_render_locks; // number of locks forcing rendering 181 182 struct wl_list cursors; // wlr_output_cursor::link 183 struct wlr_output_cursor *hardware_cursor; 184 int software_cursor_locks; // number of locks forcing software cursors 185 186 struct wl_listener display_destroy; 187 188 void *data; 189 }; 190 191 struct wlr_output_event_damage { 192 struct wlr_output *output; 193 pixman_region32_t *damage; // output-buffer-local coordinates 194 }; 195 196 struct wlr_output_event_precommit { 197 struct wlr_output *output; 198 struct timespec *when; 199 }; 200 201 struct wlr_output_event_commit { 202 struct wlr_output *output; 203 uint32_t committed; // bitmask of enum wlr_output_state_field 204 struct timespec *when; 205 }; 206 207 enum wlr_output_present_flag { 208 // The presentation was synchronized to the "vertical retrace" by the 209 // display hardware such that tearing does not happen. 210 WLR_OUTPUT_PRESENT_VSYNC = 0x1, 211 // The display hardware provided measurements that the hardware driver 212 // converted into a presentation timestamp. 213 WLR_OUTPUT_PRESENT_HW_CLOCK = 0x2, 214 // The display hardware signalled that it started using the new image 215 // content. 216 WLR_OUTPUT_PRESENT_HW_COMPLETION = 0x4, 217 // The presentation of this update was done zero-copy. 218 WLR_OUTPUT_PRESENT_ZERO_COPY = 0x8, 219 }; 220 221 struct wlr_output_event_present { 222 struct wlr_output *output; 223 // Frame submission for which this presentation event is for (see 224 // wlr_output.commit_seq). 225 uint32_t commit_seq; 226 // Time when the content update turned into light the first time. 227 struct timespec *when; 228 // Vertical retrace counter. Zero if unavailable. 229 unsigned seq; 230 // Prediction of how many nanoseconds after `when` the very next output 231 // refresh may occur. Zero if unknown. 232 int refresh; // nsec 233 uint32_t flags; // enum wlr_output_present_flag 234 }; 235 236 struct wlr_surface; 237 238 /** 239 * Enables or disables the output. A disabled output is turned off and doesn't 240 * emit `frame` events. 241 * 242 * Whether an output is enabled is double-buffered state, see 243 * `wlr_output_commit`. 244 */ 245 void wlr_output_enable(struct wlr_output *output, bool enable); 246 void wlr_output_create_global(struct wlr_output *output); 247 void wlr_output_destroy_global(struct wlr_output *output); 248 /** 249 * Returns the preferred mode for this output. If the output doesn't support 250 * modes, returns NULL. 251 */ 252 struct wlr_output_mode *wlr_output_preferred_mode(struct wlr_output *output); 253 /** 254 * Sets the output mode. The output needs to be enabled. 255 * 256 * Mode is double-buffered state, see `wlr_output_commit`. 257 */ 258 void wlr_output_set_mode(struct wlr_output *output, 259 struct wlr_output_mode *mode); 260 /** 261 * Sets a custom mode on the output. If modes are available, they are preferred. 262 * Setting `refresh` to zero lets the backend pick a preferred value. The 263 * output needs to be enabled. 264 * 265 * Custom mode is double-buffered state, see `wlr_output_commit`. 266 */ 267 void wlr_output_set_custom_mode(struct wlr_output *output, int32_t width, 268 int32_t height, int32_t refresh); 269 /** 270 * Sets a transform for the output. 271 * 272 * Transform is double-buffered state, see `wlr_output_commit`. 273 */ 274 void wlr_output_set_transform(struct wlr_output *output, 275 enum wl_output_transform transform); 276 /** 277 * Enables or disables adaptive sync (ie. variable refresh rate) on this 278 * output. This is just a hint, the backend is free to ignore this setting. 279 * 280 * When enabled, compositors can submit frames a little bit later than the 281 * deadline without dropping a frame. 282 * 283 * Adaptive sync is double-buffered state, see `wlr_output_commit`. 284 */ 285 void wlr_output_enable_adaptive_sync(struct wlr_output *output, bool enabled); 286 /** 287 * Sets a scale for the output. 288 * 289 * Scale is double-buffered state, see `wlr_output_commit`. 290 */ 291 void wlr_output_set_scale(struct wlr_output *output, float scale); 292 void wlr_output_set_subpixel(struct wlr_output *output, 293 enum wl_output_subpixel subpixel); 294 void wlr_output_set_description(struct wlr_output *output, const char *desc); 295 /** 296 * Schedule a done event. 297 * 298 * This is intended to be used by wl_output add-on interfaces. 299 */ 300 void wlr_output_schedule_done(struct wlr_output *output); 301 void wlr_output_destroy(struct wlr_output *output); 302 /** 303 * Computes the transformed output resolution. 304 */ 305 void wlr_output_transformed_resolution(struct wlr_output *output, 306 int *width, int *height); 307 /** 308 * Computes the transformed and scaled output resolution. 309 */ 310 void wlr_output_effective_resolution(struct wlr_output *output, 311 int *width, int *height); 312 /** 313 * Attach the renderer's buffer to the output. Compositors must call this 314 * function before rendering. After they are done rendering, they should call 315 * `wlr_output_commit` to submit the new frame. The output needs to be 316 * enabled. 317 * 318 * If non-NULL, `buffer_age` is set to the drawing buffer age in number of 319 * frames or -1 if unknown. This is useful for damage tracking. 320 * 321 * If the compositor decides not to render after calling this function, it 322 * must call wlr_output_rollback. 323 */ 324 bool wlr_output_attach_render(struct wlr_output *output, int *buffer_age); 325 /** 326 * Attach a buffer to the output. Compositors should call `wlr_output_commit` 327 * to submit the new frame. The output needs to be enabled. 328 * 329 * Not all backends support direct scan-out on all buffers. Compositors can 330 * check whether a buffer is supported by calling `wlr_output_test`. 331 */ 332 void wlr_output_attach_buffer(struct wlr_output *output, 333 struct wlr_buffer *buffer); 334 /** 335 * Get the preferred format for reading pixels. 336 * This function might change the current rendering context. 337 */ 338 bool wlr_output_preferred_read_format(struct wlr_output *output, 339 enum wl_shm_format *fmt); 340 /** 341 * Set the damage region for the frame to be submitted. This is the region of 342 * the screen that has changed since the last frame. 343 * 344 * Compositors implementing damage tracking should call this function with the 345 * damaged region in output-buffer-local coordinates (ie. scaled and 346 * transformed). 347 * 348 * This region is not to be confused with the renderer's buffer damage, ie. the 349 * region compositors need to repaint. Compositors usually need to repaint more 350 * than what changed since last frame since multiple render buffers are used. 351 */ 352 void wlr_output_set_damage(struct wlr_output *output, 353 pixman_region32_t *damage); 354 /** 355 * Test whether the pending output state would be accepted by the backend. If 356 * this function returns true, `wlr_output_commit` can only fail due to a 357 * runtime error. 358 * 359 * This function doesn't mutate the pending state. 360 */ 361 bool wlr_output_test(struct wlr_output *output); 362 /** 363 * Commit the pending output state. If `wlr_output_attach_render` has been 364 * called, the pending frame will be submitted for display and a `frame` event 365 * will be scheduled. 366 * 367 * On failure, the pending changes are rolled back. 368 */ 369 bool wlr_output_commit(struct wlr_output *output); 370 /** 371 * Discard the pending output state. 372 */ 373 void wlr_output_rollback(struct wlr_output *output); 374 /** 375 * Manually schedules a `frame` event. If a `frame` event is already pending, 376 * it is a no-op. 377 */ 378 void wlr_output_schedule_frame(struct wlr_output *output); 379 /** 380 * Returns the maximum length of each gamma ramp, or 0 if unsupported. 381 */ 382 size_t wlr_output_get_gamma_size(struct wlr_output *output); 383 /** 384 * Sets the gamma table for this output. `r`, `g` and `b` are gamma ramps for 385 * red, green and blue. `size` is the length of the ramps and must not exceed 386 * the value returned by `wlr_output_get_gamma_size`. 387 * 388 * Providing zero-sized ramps resets the gamma table. 389 * 390 * The gamma table is double-buffered state, see `wlr_output_commit`. 391 */ 392 void wlr_output_set_gamma(struct wlr_output *output, size_t size, 393 const uint16_t *r, const uint16_t *g, const uint16_t *b); 394 /** 395 * Exports the last committed buffer as a DMA-BUF. 396 * 397 * The caller is responsible for cleaning up the DMA-BUF attributes. 398 */ 399 bool wlr_output_export_dmabuf(struct wlr_output *output, 400 struct wlr_dmabuf_attributes *attribs); 401 /** 402 * Returns the wlr_output matching the provided wl_output resource. If the 403 * resource isn't a wl_output, it aborts. If the resource is inert (because the 404 * wlr_output has been destroyed), NULL is returned. 405 */ 406 struct wlr_output *wlr_output_from_resource(struct wl_resource *resource); 407 /** 408 * Locks the output to only use rendering instead of direct scan-out. This is 409 * useful if direct scan-out needs to be temporarily disabled (e.g. during 410 * screen capture). There must be as many unlocks as there have been locks to 411 * restore the original state. There should never be an unlock before a lock. 412 */ 413 void wlr_output_lock_attach_render(struct wlr_output *output, bool lock); 414 /** 415 * Locks the output to only use software cursors instead of hardware cursors. 416 * This is useful if hardware cursors need to be temporarily disabled (e.g. 417 * during screen capture). There must be as many unlocks as there have been 418 * locks to restore the original state. There should never be an unlock before 419 * a lock. 420 */ 421 void wlr_output_lock_software_cursors(struct wlr_output *output, bool lock); 422 /** 423 * Renders software cursors. This is a utility function that can be called when 424 * compositors render. 425 */ 426 void wlr_output_render_software_cursors(struct wlr_output *output, 427 pixman_region32_t *damage); 428 429 430 struct wlr_output_cursor *wlr_output_cursor_create(struct wlr_output *output); 431 /** 432 * Sets the cursor image. The image must be already scaled for the output. 433 */ 434 bool wlr_output_cursor_set_image(struct wlr_output_cursor *cursor, 435 const uint8_t *pixels, int32_t stride, uint32_t width, uint32_t height, 436 int32_t hotspot_x, int32_t hotspot_y); 437 void wlr_output_cursor_set_surface(struct wlr_output_cursor *cursor, 438 struct wlr_surface *surface, int32_t hotspot_x, int32_t hotspot_y); 439 bool wlr_output_cursor_move(struct wlr_output_cursor *cursor, 440 double x, double y); 441 void wlr_output_cursor_destroy(struct wlr_output_cursor *cursor); 442 443 444 /** 445 * Returns the transform that, when composed with `tr`, gives 446 * `WL_OUTPUT_TRANSFORM_NORMAL`. 447 */ 448 enum wl_output_transform wlr_output_transform_invert( 449 enum wl_output_transform tr); 450 451 /** 452 * Returns a transform that, when applied, has the same effect as applying 453 * sequentially `tr_a` and `tr_b`. 454 */ 455 enum wl_output_transform wlr_output_transform_compose( 456 enum wl_output_transform tr_a, enum wl_output_transform tr_b); 457 458 #endif 459