l4/pkg/l4re_c/include/video/view.h

   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