1 /**
2  * \file
3  * \note The C interface of L4Re::Video does _NOT_ reflect the full C++
4  *       interface on purpose. Use the C++ where possible.
5  */
6 /*
7  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>
8  *     economic rights: Technische Universität Dresden (Germany)
9  *
10  * This file is part of TUD:OS and distributed under the terms of the
11  * GNU General Public License 2.
12  * Please see the COPYING-GPL-2 file for details.
13  *
14  * As a special exception, you may use this file as part of a free software
15  * library without restriction.  Specifically, if other files instantiate
16  * templates or use macros or inline functions from this file, or you compile
17  * this file and link it with other files to produce an executable, this
18  * file does not by itself cause the resulting executable to be covered by
19  * the GNU General Public License.  This exception does not however
20  * invalidate any other reasons why the executable file might be covered by
21  * the GNU General Public License.
22  */
23 #pragma once
24 
25 #include <l4/sys/types.h>
26 #include <l4/re/c/dataspace.h>
27 #include <l4/re/c/video/colors.h>
28 
29 /**
30  * \brief Flags of information on a view.
31  * \ingroup api_l4re_c_video
32  */
33 enum l4re_video_view_info_flags_t
34 {
35   F_l4re_video_view_none               = 0x00, ///< everything for this view is static (the VESA-FB case)
36   F_l4re_video_view_set_buffer         = 0x01, ///< buffer object for this view can be changed
37   F_l4re_video_view_set_buffer_offset  = 0x02, ///< buffer offset can be set
38   F_l4re_video_view_set_bytes_per_line = 0x04, ///< bytes per line can be set
39   F_l4re_video_view_set_pixel          = 0x08, ///< pixel type can be set
40   F_l4re_video_view_set_position       = 0x10, ///< position on screen can be set
41   F_l4re_video_view_dyn_allocated      = 0x20, ///< View is dynamically allocated
42   F_l4re_video_view_set_background     = 0x40, ///< Set view as background for session
43   F_l4re_video_view_set_flags          = 0x80, ///< Set view property flags
44   F_l4re_video_view_fully_dynamic      =   F_l4re_video_view_set_buffer
45                                          | F_l4re_video_view_set_buffer_offset
46                                          | F_l4re_video_view_set_bytes_per_line
47                                          | F_l4re_video_view_set_pixel
48                                          | F_l4re_video_view_set_position
49                                          | F_l4re_video_view_dyn_allocated,
50 
51   F_l4re_video_view_above      = 0x01000, ///< Flag the view as stay on top
52   F_l4re_video_view_flags_mask = 0xff000, ///< Mask containing all possible property flags
53 };
54 
55 /**
56  * \brief View information structure
57  * \ingroup api_l4re_c_video
58  */
59 typedef struct l4re_video_view_info_t
60 {
61   unsigned                flags;                     ///< Flags
62   unsigned                view_index;                ///< Number of view in the goos
63   unsigned long           xpos, ypos, width, height; ///< Position in goos and size of view
64   unsigned long           buffer_offset;             ///< Memory offset in goos buffer
65   unsigned long           bytes_per_line;            ///< Size of line in view
66   l4re_video_pixel_info_t pixel_info;                ///< Pixel info
67   unsigned                buffer_index;              ///< Number of buffer of goos
68 } l4re_video_view_info_t;
69 
70 
71 /**
72  * \brief C representation of a goos view.
73  * \ingroup api_l4re_c_video
74  *
75  * A view is a visible rectangle that provides a view to the contents of a
76  * buffer (frame buffer) memory object and is placed on a real screen.
77  */
78 typedef struct l4re_video_view_t
79 {
80   l4_cap_idx_t goos;
81   unsigned idx;
82 } l4re_video_view_t;
83 
84 
85 EXTERN_C_BEGIN
86 
87 /**
88  * \ingroup api_l4re_c_video
89  * \brief Flush the given rectangle of pixels of the given \a view.
90  * \param view the target view of the operation.
91  * \param x x-coordinate of the upper left corner
92  * \param y y-coordinate of the upper left corner
93  * \param w the width of the rectangle
94  * \param h the height of the rectangle
95  */
96 L4_CV int
97 l4re_video_view_refresh(l4re_video_view_t *view, int x, int y, int w,
98                         int h) L4_NOTHROW;
99 
100 /**
101  * \ingroup api_l4re_c_video
102  * \brief Retrieve information about the given \a view.
103  * \param view the target view for the operation.
104  * \retval info a buffer receiving the information about the view.
105  */
106 L4_CV int
107 l4re_video_view_get_info(l4re_video_view_t *view,
108                          l4re_video_view_info_t *info) L4_NOTHROW;
109 
110 /**
111  * \ingroup api_l4re_c_video
112  * \brief Set properties of the view.
113  * \param view the target view of the operation.
114  * \param info the parameters to be set on the view.
115  *
116  * Which parameters can be manipulated on a given view can be figured out
117  * with l4re_video_view_get_info() and this depends on the concrete instance
118  * the view object.
119  */
120 L4_CV int
121 l4re_video_view_set_info(l4re_video_view_t *view,
122                          l4re_video_view_info_t *info) L4_NOTHROW;
123 
124 /**
125  * \ingroup api_l4re_c_video
126  * \brief Set the viewport parameters of a view.
127  * \param view the target view of the operation.
128  * \param x the x-coordinate of the upper left corner on the screen.
129  * \param y the y-coordinate of the upper left corner on the screen.
130  * \param w the width of the view.
131  * \param h the height of the view.
132  * \param bofs the offset (in bytes) of the upper left pixel in
133  *             the memory buffer
134  *
135  * This function is a convenience wrapper for l4re_video_view_set_info(), just setting
136  * the often changed parameters of a dynamic view. With this function a view
137  * can be placed on the real screen and at the same time on its backing buffer.
138  */
139 L4_CV int
140 l4re_video_view_set_viewport(l4re_video_view_t *view, int x, int y, int w,
141                              int h, unsigned long bofs) L4_NOTHROW;
142 
143 /**
144  * \ingroup api_l4re_c_video
145  * \brief Change the stacking order in the stack of visible views.
146  * \param view the target view for the operation.
147  * \param pivot the neighbor view, relative to which \a view shall be stacked.
148  *              a NULL value allows top (\a behind = 1) and bottom
149  *              (\a behind = 0) placement of the view.
150  * \param behind describes the placement of the view relative to the \a pivot view.
151  */
152 L4_CV int
153 l4re_video_view_stack(l4re_video_view_t *view, l4re_video_view_t *pivot,
154                       int behind) L4_NOTHROW;
155 
156 EXTERN_C_END
157 
158