1/* swc: libswc/view.h
  2 *
  3 * Copyright (c) 2013 Michael Forney
  4 *
  5 * Permission is hereby granted, free of charge, to any person obtaining a copy
  6 * of this software and associated documentation files (the "Software"), to deal
  7 * in the Software without restriction, including without limitation the rights
  8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9 * copies of the Software, and to permit persons to whom the Software is
 10 * furnished to do so, subject to the following conditions:
 11 *
 12 * The above copyright notice and this permission notice shall be included in
 13 * all copies or substantial portions of the Software.
 14 *
 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 21 * SOFTWARE.
 22 */
 23
 24#ifndef SWC_VIEW_H
 25#define SWC_VIEW_H
 26
 27#include "swc.h"
 28
 29#include <wayland-util.h>
 30
 31/**
 32 * A view represents a component that can display buffers to the user.
 33 *
 34 * For example, each output contains a view residing in its framebuffer plane
 35 * that is used to scan out buffers. Additionally, the compositor creates views
 36 * dynamically for each surface it displays, compositing them into a single
 37 * buffer, which it can then attach to the previously mentioned view.
 38 *
 39 * This abstraction allows various components of swc to connect in a general
 40 * way, allowing operations like setting the output view of a surface directly
 41 * to an output's framebuffer plane, bypassing the compositor.
 42 */
 43struct view {
 44	const struct view_impl *impl;
 45	struct wl_list handlers;
 46
 47	struct swc_rectangle geometry;
 48	uint32_t screens;
 49
 50	struct wld_buffer *buffer;
 51};
 52
 53struct view_handler {
 54	const struct view_handler_impl *impl;
 55	struct wl_list link;
 56};
 57
 58/**
 59 * Every view must have an implementation containing these functions.
 60 *
 61 * For descriptions, see the corresponding view_* function.
 62 */
 63struct view_impl {
 64	bool (*update)(struct view *view);
 65	int (*attach)(struct view *view, struct wld_buffer *buffer);
 66	bool (*move)(struct view *view, int32_t x, int32_t y);
 67};
 68
 69struct view_handler_impl {
 70	/* Called when the view has displayed the next frame. */
 71	void (*frame)(struct view_handler *handler, uint32_t time);
 72	/* Called when a new buffer is attached to the view. */
 73	void (*attach)(struct view_handler *handler);
 74	/* Called after the view's position changes. */
 75	void (*move)(struct view_handler *handler);
 76	/* Called after the view's size changes. */
 77	void (*resize)(struct view_handler *handler, uint32_t old_width,
 78	               uint32_t old_height);
 79	/* Called when the set of screens the view is visible on changes. */
 80	void (*screens)(struct view_handler *handler, uint32_t left,
 81	                uint32_t entered);
 82};
 83
 84/**
 85 * Attach a new buffer to the view.
 86 *
 87 * If buffer is NULL, the previous buffer is removed from the view.
 88 *
 89 * @return 0 on success, negative error code otherwise.
 90 */
 91int
 92view_attach(struct view *view, struct wld_buffer *buffer);
 93
 94/**
 95 * Display a new frame consisting of the currently attached buffer.
 96 *
 97 * @return Whether or not the update succeeds.
 98 */
 99bool
100view_update(struct view *view);
101
102/**
103 * Move the view to the specified coordinates, if supported.
104 *
105 * @return Whether or not the move succeeds.
106 */
107bool
108view_move(struct view *view, int32_t x, int32_t y);
109
110/**** For internal view use only ****/
111
112/**
113 * Initialize a new view with the specified implementation.
114 */
115void
116view_initialize(struct view *view, const struct view_impl *impl);
117
118/**
119 * Release any resources associated with this view.
120 */
121void
122view_finalize(struct view *view);
123
124bool
125view_set_position(struct view *view, int32_t x, int32_t y);
126bool
127view_set_size(struct view *view, uint32_t width, uint32_t height);
128bool
129view_set_size_from_buffer(struct view *view, struct wld_buffer *bufer);
130void
131view_set_screens(struct view *view, uint32_t screens);
132void
133view_update_screens(struct view *view);
134
135/**
136 * Send a new frame event through the view's event signal.
137 *
138 * This should be called by the view itself when the next frame is visible to
139 * the user. If time information is not available, get_time() can be passed
140 * instead.
141 */
142void
143view_frame(struct view *view, uint32_t time);
144
145#endif