payloads/libpayload/include/cbgfx.h

   1 /*
   2  *
   3  * Copyright (C) 2015 Google, Inc.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. The name of the author may not be used to endorse or promote products
  14  *    derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  * SUCH DAMAGE.
  27  */
  28
  29 #include <libpayload.h>
  30 #include <arch/types.h>
  31 #include <stddef.h>
  32
  33 /*
  34  * API error codes
  35  */
  36 #define CBGFX_SUCCESS                   0
  37 /* unknown error */
  38 #define CBGFX_ERROR_UNKNOWN             1
  39 /* failed to initialize cbgfx library */
  40 #define CBGFX_ERROR_INIT                2
  41 /* drawing beyond screen or canvas boundary */
  42 #define CBGFX_ERROR_BOUNDARY            3
  43 /* invalid parameter */
  44 #define CBGFX_ERROR_INVALID_PARAMETER   4
  45 /* bitmap error: signature mismatch */
  46 #define CBGFX_ERROR_BITMAP_SIGNATURE    0x10
  47 /* bitmap error: unsupported format */
  48 #define CBGFX_ERROR_BITMAP_FORMAT       0x11
  49 /* bitmap error: invalid data */
  50 #define CBGFX_ERROR_BITMAP_DATA         0x12
  51 /* bitmap error: scaling out of range */
  52 #define CBGFX_ERROR_SCALE_OUT_OF_RANGE  0x13
  53 /* invalid framebuffer info */
  54 #define CBGFX_ERROR_FRAMEBUFFER_INFO    0x14
  55 /* invalid framebuffer address */
  56 #define CBGFX_ERROR_FRAMEBUFFER_ADDR    0x15
  57 /* portrait screen not supported */
  58 #define CBGFX_ERROR_PORTRAIT_SCREEN     0x16
  59 /* cannot use buffered I/O */
  60 #define CBGFX_ERROR_GRAPHICS_BUFFER     0x17
  61
  62 struct fraction {
  63         int32_t n;
  64         int32_t d;
  65 };
  66
  67 struct scale {
  68         struct fraction x;
  69         struct fraction y;
  70 };
  71
  72 struct vector {
  73         union {
  74                 int32_t x;
  75                 int32_t width;
  76         };
  77         union {
  78                 int32_t y;
  79                 int32_t height;
  80         };
  81 };
  82
  83 struct rect {
  84         struct vector offset;
  85         struct vector size;
  86 };
  87
  88 struct rgb_color {
  89         uint8_t red;
  90         uint8_t green;
  91         uint8_t blue;
  92 };
  93
  94 /*
  95  * Resolution of scale parameters used to describe height, width, coordinate,
  96  * etc. relative to the canvas. For example, if it's 100, scales range from 0 to
  97  * 100%.
  98  */
  99 #define CANVAS_SCALE            100
 100
 101 /*
 102  * The coordinate system is expected to have (0, 0) at top left corner with
 103  * y values increasing towards bottom of screen.
 104  */
 105
 106 /**
 107  * draw a box filled with a color on screen
 108  *
 109  * box: .offset points the coordinate of the top left corner and .size specifies
 110  * width and height of the box. Both are relative to the canvas size thus scale
 111  * from 0 to CANVAS_SCALE (0 to 100%).
 112  * rgb: RGB color of the box.
 113  *
 114  * return: CBGFX_* error codes
 115  */
 116 int draw_box(const struct rect *box, const struct rgb_color *rgb);
 117
 118 /**
 119  * Draw a box with rounded corners on screen.
 120  *
 121  * @param[in] pos_rel   Coordinate of the top left corner of the box relative to
 122  *                      the canvas.
 123  * @param[in] dim_rel   Width and height of the image relative to the canvas.
 124  * @param[in] rgb       Color of the border of the box.
 125  * @param[in] thickness Thickness of the border relative to the canvas. If zero
 126  *                      is given, the box will be filled with the rgb color.
 127  * @param[in] radius    Radius of the rounded corners relative to the canvas. A
 128  *                      zero value indicates sharp corners will be drawn.
 129  *
 130  * @return CBGFX_* error codes
 131  */
 132 int draw_rounded_box(const struct scale *pos_rel, const struct scale *dim_rel,
 133                      const struct rgb_color *rgb,
 134                      const struct fraction *thickness,
 135                      const struct fraction *radius);
 136
 137 /**
 138  * Draw a horizontal or vertical line segment on screen. If horizontal, pos1
 139  * must be the left endpoint. If vertical, pos1 must be the top endpoint. When
 140  * the specified thickness is zero (or truncated to zero), a line with 1-pixel
 141  * width will be drawn.
 142  *
 143  * @param[in] pos1      Start position of the line relative to the canvas.
 144  * @param[in] pos2      End position of the line relative to the canvas.
 145  * @param[in] thickness Thickness of the line relative to the canvas.
 146  * @param[in] rgb       Color of the line.
 147  *
 148  * @return CBGFX_* error codes
 149  */
 150 int draw_line(const struct scale *pos1, const struct scale *pos2,
 151               const struct fraction *thickness, const struct rgb_color *rgb);
 152
 153 /**
 154  * Clear the canvas
 155  */
 156 int clear_canvas(const struct rgb_color *rgb);
 157
 158 /**
 159  * Clear the screen
 160  */
 161 int clear_screen(const struct rgb_color *rgb);
 162
 163 /**
 164  * Draw a bitmap image using position and size relative to the canvas
 165  *
 166  * @param[in] bitmap    Pointer to the bitmap data, starting from file header
 167  * @param[in] size      Size of the bitmap data
 168  * @param[in] pos_rel   Coordinate of the pivot relative to the canvas
 169  * @param[in] dim_rel   Width and height of the image relative to the canvas
 170  *                      width and height. They must not exceed 1 (=100%). If one
 171  *                      is zero, it's derived from the other to keep the aspect
 172  *                      ratio.
 173  * @param[in] flags     lower 8 bits is Pivot position. Use PIVOT_H_* and
 174  *                      PIVOT_V_* flags.
 175  *                      Bit 9 is bit to indicate if we invert the rendering.
 176  *                      0 = render image as is, 1 = invert image.
 177  *
 178  * @return CBGFX_* error codes
 179  *
 180  * 'Pivot' is a point of the image based on which the image is positioned.
 181  * For example, if a pivot is set to PIVOT_H_CENTER|PIVOT_V_CENTER, the image is
 182  * positioned so that pos_rel matches the center of the image.
 183  */
 184 int draw_bitmap(const void *bitmap, size_t size,
 185                 const struct scale *pos_rel, const struct scale *dim_rel,
 186                 uint32_t flags);
 187
 188 /* Pivot flags. See the draw_bitmap description. */
 189 #define PIVOT_H_LEFT    (1 << 0)
 190 #define PIVOT_H_CENTER  (1 << 1)
 191 #define PIVOT_H_RIGHT   (1 << 2)
 192 #define PIVOT_V_TOP     (1 << 3)
 193 #define PIVOT_V_CENTER  (1 << 4)
 194 #define PIVOT_V_BOTTOM  (1 << 5)
 195 #define PIVOT_MASK      0x000000ff
 196
 197 /* invert flag */
 198 #define INVERT_SHIFT    8
 199 #define INVERT_COLORS   (1 << INVERT_SHIFT)
 200
 201 /**
 202  * Draw a bitmap image at screen coordinate with no scaling
 203  *
 204  * @param[in] bitmap    Pointer to the bitmap data, starting from file header
 205  * @param[in] size      Size of the bitmap data
 206  * @param[in] pos       Screen coordinate of upper left corner of the image.
 207  *
 208  * @return CBGFX_* error codes
 209  */
 210 int draw_bitmap_direct(const void *bitmap, size_t size,
 211                        const struct vector *top_left);
 212
 213 /**
 214  * Get width and height of projected image
 215  *
 216  * @param[in] bitmap    Pointer to the bitmap data, starting from file header
 217  * @param[in] sz        Size of the bitmap data
 218  * @param[i/o] dim_rel  Width and height of the image relative to the canvas
 219  *                      width and height. They must not exceed 1 (=100%).
 220  *                      On return, it contains automatically calculated width
 221  *                      and/or height.
 222  *
 223  * @return CBGFX_* error codes
 224  *
 225  * It returns the width and height of the projected image. If the input height
 226  * is zero, it's derived from the input width to keep the aspect ratio, and vice
 227  * versa. If both are zero, the width and the height which can project the image
 228  * in the original size are returned.
 229  */
 230 int get_bitmap_dimension(const void *bitmap, size_t sz, struct scale *dim_rel);
 231
 232 /**
 233  * Setup color mappings of background and foreground colors. Black and white
 234  * pixels will be mapped to the background and foreground colors, respectively.
 235  * Call clear_color_map() to disabled color mapping.
 236  *
 237  * @param[in] background        Background color.
 238  * @param[in] foreground        Foreground color.
 239  *
 240  * @return CBGFX_* error codes
 241  */
 242 int set_color_map(const struct rgb_color *background,
 243                   const struct rgb_color *foreground);
 244
 245 /**
 246  * Clear color mappings.
 247  */
 248 void clear_color_map(void);
 249
 250 /**
 251  * Setup alpha and rgb values for alpha blending.  When alpha is != 0,
 252  * this enables a translucent layer of color (defined by rgb) to be
 253  * blended at a given translucency (alpha) to all things drawn.  Call
 254  * clear_blend() to disable alpha blending.
 255  *
 256  * @param[in] rgb       Color for transparency
 257  * @param[in] alpha     Opacity of color, from 0-255 where
 258  *                      0   = completely transparent (no blending)
 259  *                      255 = max alpha argument
 260  *
 261  * @return CBGFX_* error codes
 262  */
 263 int set_blend(const struct rgb_color *rgb, uint8_t alpha);
 264
 265 /**
 266  * Clear alpha and rgb values, thus disabling any alpha blending.
 267  */
 268 void clear_blend(void);
 269
 270 /**
 271  * For calculating Alpha value from % opacity
 272  * For reference:
 273  *      255 = max alpha argument
 274  *      0   = min alpha argument, 0% opacity
 275  */
 276 #define ALPHA(percentage) MIN(255, (256 * percentage / 100))
 277
 278 /**
 279  * Enable buffered I/O. All CBGFX operations will be redirected to a working
 280  * buffer, and only updated (redrawn) when flush_graphics_buffer() is called.
 281  *
 282  * @return CBGFX_* error codes
 283  */
 284 int enable_graphics_buffer(void);
 285
 286 /**
 287  * Redraw buffered graphics data to real screen if graphics buffer is already
 288  * enabled.
 289  *
 290  * @return CBGFX_* error codes
 291  */
 292 int flush_graphics_buffer(void);
 293
 294 /**
 295  * Stop using buffered I/O and release allocated memory.
 296  */
 297 void disable_graphics_buffer(void);