l4/pkg/l4re-core/l4re_c/include/video/goos.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 #include <l4/re/c/video/view.h>
  29
  30 /**
  31  * \defgroup api_l4re_c_video Video API
  32  * \ingroup api_l4re_c
  33  */
  34
  35 /**
  36  * \brief Flags of information on the goos.
  37  * \ingroup api_l4re_c_video
  38  */
  39 enum l4re_video_goos_info_flags_t
  40 {
  41   F_l4re_video_goos_auto_refresh    = 0x01, ///< The graphics display is automatically refreshed
  42   F_l4re_video_goos_pointer         = 0x02, ///< We have a mouse pointer
  43   F_l4re_video_goos_dynamic_views   = 0x04, ///< Supports dynamically allocated views
  44   F_l4re_video_goos_dynamic_buffers = 0x08, ///< Supports dynamically allocated buffers
  45 };
  46
  47 /**
  48  * \brief Goos information structure
  49  * \ingroup api_l4re_c_video
  50  */
  51 typedef struct
  52 {
  53   unsigned long width;                ///< Width of the goos
  54   unsigned long height;               ///< Height of the goos
  55   unsigned flags;                     ///< Flags of the framebuffer, see #l4re_video_goos_info_flags_t
  56   unsigned num_static_views;          ///< Number of static views
  57   unsigned num_static_buffers;        ///< Number of static buffers
  58   l4re_video_pixel_info_t pixel_info; ///< Pixel layout of the goos
  59 } l4re_video_goos_info_t;
  60
  61 /**
  62  * \brief Goos object type
  63  * \ingroup api_l4re_c_fb
  64  */
  65 typedef l4_cap_idx_t l4re_video_goos_t;
  66
  67 EXTERN_C_BEGIN
  68
  69 /**
  70  * \brief Get information on a goos.
  71  * \ingroup api_l4re_c_video
  72  *
  73  * \param  goos  Goos object
  74  * \retval ginfo Pointer to goos information structure.
  75  *
  76  * \return 0 for success, <0 on error
  77  *         - -#L4_ENODEV
  78  *         - IPC errors
  79  */
  80 L4_CV int
  81 l4re_video_goos_info(l4re_video_goos_t goos,
  82                      l4re_video_goos_info_t *ginfo) L4_NOTHROW;
  83
  84 /**
  85  * \ingroup api_l4re_c_video
  86  * \brief Flush a rectangle of pixels of the goos screen.
  87  * \param goos the target object of the operation.
  88  * \param x the x-coordinate of the upper left corner of the rectangle
  89  * \param y the y-coordinate of the upper left corner of the rectangle
  90  * \param w the width of the rectangle to be flushed
  91  * \param h the height of the rectangle
  92  */
  93 L4_CV int
  94 l4re_video_goos_refresh(l4re_video_goos_t goos, int x, int y, int w,
  95                         int h) L4_NOTHROW;
  96
  97 /**
  98  * \ingroup api_l4re_c_video
  99  * \brief Create a new buffer (memory buffer) for pixel data.
 100  * \param goos the target object for the operation.
 101  * \param size the size in bytes for the pixel buffer.
 102  * \param buffer a capability index to receive the data-space capability
 103  *               for the buffer.
 104  * \return >=0: The index of the created buffer (used to assign views
 105  *               and for deletion).
 106  *         < 0: on error
 107  */
 108 L4_CV int
 109 l4re_video_goos_create_buffer(l4re_video_goos_t goos, unsigned long size,
 110                               l4_cap_idx_t buffer) L4_NOTHROW;
 111
 112 /**
 113  * \ingroup api_l4re_c_video
 114  * \brief Delete a pixel buffer.
 115  * \param goos the target goos object.
 116  * \param idx the buffer index of the buffer to delete (the return
 117  *            value of l4re_video_goos_create_buffer())
 118  */
 119 L4_CV int
 120 l4re_video_goos_delete_buffer(l4re_video_goos_t goos, unsigned idx) L4_NOTHROW;
 121
 122 /**
 123  * \ingroup api_l4re_c_video
 124  * \brief Get the data-space capability of the static pixel buffer.
 125  * \param goos    The target goos object.
 126  * \param idx     Index of the static buffer.
 127  * \param buffer  A capability index to receive the data-space capability.
 128  *
 129  * This function allows access to static, preexisting pixel buffers. Such static buffers
 130  * exist for static configurations, such as the VESA framebuffer.
 131  */
 132 L4_CV int
 133 l4re_video_goos_get_static_buffer(l4re_video_goos_t goos, unsigned idx,
 134                                   l4_cap_idx_t buffer) L4_NOTHROW;
 135
 136 /**
 137  * \ingroup api_l4re_c_video
 138  * \brief Create a new view (\see l4re_video_view_t)
 139  * \param goos the goos session to use.
 140  * \retval view the structure will be initialized for the new view.
 141  */
 142 L4_CV int
 143 l4re_video_goos_create_view(l4re_video_goos_t goos,
 144                             l4re_video_view_t *view) L4_NOTHROW;
 145
 146 /**
 147  * \ingroup api_l4re_c_video
 148  * \brief Delete a view.
 149  * \param goos the goos session to use.
 150  * \param view the view to delete, the given data-structure is invalid
 151  *             afterwards.
 152  */
 153 L4_CV int
 154 l4re_video_goos_delete_view(l4re_video_goos_t goos,
 155                             l4re_video_view_t *view) L4_NOTHROW;
 156
 157
 158 /**
 159  * \ingroup api_l4re_c_video
 160  * \brief Get a view for the given index.
 161  * \param goos the target goos session.
 162  * \param idx the index of the view to retrieve.
 163  * \retval view the structure will be initialized to the
 164  *              view with the given index.
 165  *
 166  * This function allows to access static views as provided by the
 167  * VESA framebuffer (the monitor). However, it also allows to access
 168  * dynamic views created with l4re_video_goos_create_view().
 169  */
 170 L4_CV int
 171 l4re_video_goos_get_view(l4re_video_goos_t goos, unsigned idx,
 172                          l4re_video_view_t *view) L4_NOTHROW;
 173
 174 EXTERN_C_END