MdePkg/Include/Protocol/HiiImage.h

   1 /** @file
   2   The file provides services to access to images in the images database.
   3
   4   Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __HII_IMAGE_H__
  16 #define __HII_IMAGE_H__
  17
  18 #include <Protocol/GraphicsOutput.h>
  19
  20 #define EFI_HII_IMAGE_PROTOCOL_GUID \
  21   { 0x31a6406a, 0x6bdf, 0x4e46, { 0xb2, 0xa2, 0xeb, 0xaa, 0x89, 0xc4, 0x9, 0x20 } }
  22
  23 typedef struct _EFI_HII_IMAGE_PROTOCOL EFI_HII_IMAGE_PROTOCOL;
  24
  25
  26 ///
  27 /// Flags in EFI_IMAGE_INPUT
  28 ///
  29 #define EFI_IMAGE_TRANSPARENT 0x00000001
  30
  31 /**
  32
  33   Definition of EFI_IMAGE_INPUT.
  34
  35   @param Flags  Describe image characteristics. If
  36                 EFI_IMAGE_TRANSPARENT is set, then the image was
  37                 designed for transparent display.
  38
  39   @param Width  Image width, in pixels.
  40
  41   @param Height Image height, in pixels.
  42
  43   @param Bitmap A pointer to the actual bitmap, organized left-to-right,
  44                 top-to-bottom. The size of the bitmap is
  45                 Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL).
  46
  47
  48 **/
  49 typedef struct _EFI_IMAGE_INPUT {
  50   UINT32                          Flags;
  51   UINT16                          Width;
  52   UINT16                          Height;
  53   EFI_GRAPHICS_OUTPUT_BLT_PIXEL   *Bitmap;
  54 } EFI_IMAGE_INPUT;
  55
  56
  57 /**
  58
  59   This function adds the image Image to the group of images
  60   owned by PackageList, and returns a new image identifier
  61   (ImageId).
  62
  63   @param This        A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
  64
  65   @param PackageList Handle of the package list where this image will be added.
  66
  67   @param ImageId     On return, contains the new image id, which is
  68                      unique within PackageList.
  69
  70   @param Image       Points to the image.
  71
  72   @retval EFI_SUCCESS             The new image was added
  73                                   successfully
  74
  75   @retval EFI_OUT_OF_RESOURCES    Could not add the image.
  76
  77   @retval EFI_INVALID_PARAMETER   Image is NULL or ImageId is
  78                                   NULL.
  79
  80
  81 **/
  82 typedef
  83 EFI_STATUS
  84 (EFIAPI *EFI_HII_NEW_IMAGE)(
  85   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
  86   IN        EFI_HII_HANDLE          PackageList,
  87   OUT       EFI_IMAGE_ID            *ImageId,
  88   IN CONST  EFI_IMAGE_INPUT         *Image
  89 );
  90
  91 /**
  92
  93   This function retrieves the image specified by ImageId which
  94   is associated with the specified PackageList and copies it
  95   into the buffer specified by Image. If the image specified by
  96   ImageId is not present in the specified PackageList, then
  97   EFI_NOT_FOUND is returned. If the buffer specified by
  98   ImageSize is too small to hold the image, then
  99   EFI_BUFFER_TOO_SMALL will be returned. ImageSize will be
 100   updated to the size of buffer actually required to hold the
 101   image.
 102
 103   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 104
 105   @param PackageList  The package list in the HII database to
 106                       search for the specified image.
 107
 108   @param ImageId      The image's id, which is unique within
 109                       PackageList.
 110
 111   @param Image        Points to the new image.
 112
 113   @retval EFI_SUCCESS            The image was returned successfully.
 114
 115   @retval EFI_NOT_FOUND          The image specified by ImageId is not
 116                                  available. Or The specified PackageList is not in the database.
 117
 118   @retval EFI_INVALID_PARAMETER  The Image or Langugae was NULL.
 119   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there was not
 120                                  enough memory.
 121
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_HII_GET_IMAGE)(
 127   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 128   IN        EFI_HII_HANDLE          PackageList,
 129   IN        EFI_IMAGE_ID            ImageId,
 130   OUT       EFI_IMAGE_INPUT         *Image
 131 );
 132
 133 /**
 134
 135   This function updates the image specified by ImageId in the
 136   specified PackageListHandle to the image specified by Image.
 137
 138
 139   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 140
 141   @param PackageList  The package list containing the images.
 142
 143   @param ImageId      The image id, which is unique within PackageList.
 144
 145   @param Image        Points to the image.
 146
 147   @retval EFI_SUCCESS           The image was successfully updated.
 148
 149   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
 150                                 The specified PackageList is not in the database.
 151
 152   @retval EFI_INVALID_PARAMETER The Image or Language was NULL.
 153
 154 **/
 155 typedef
 156 EFI_STATUS
 157 (EFIAPI *EFI_HII_SET_IMAGE)(
 158   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 159   IN        EFI_HII_HANDLE          PackageList,
 160   IN        EFI_IMAGE_ID            ImageId,
 161   IN CONST  EFI_IMAGE_INPUT         *Image
 162 );
 163
 164
 165 ///
 166 /// EFI_HII_DRAW_FLAGS describes how the image is to be drawn.
 167 /// These flags are defined as EFI_HII_DRAW_FLAG_***
 168 ///
 169 typedef UINT32  EFI_HII_DRAW_FLAGS;
 170
 171 #define EFI_HII_DRAW_FLAG_CLIP          0x00000001
 172 #define EFI_HII_DRAW_FLAG_TRANSPARENT   0x00000030
 173 #define EFI_HII_DRAW_FLAG_DEFAULT       0x00000000
 174 #define EFI_HII_DRAW_FLAG_FORCE_TRANS   0x00000010
 175 #define EFI_HII_DRAW_FLAG_FORCE_OPAQUE  0x00000020
 176 #define EFI_HII_DIRECT_TO_SCREEN        0x00000080
 177
 178 /**
 179
 180   Definition of EFI_IMAGE_OUTPUT.
 181
 182   @param Width  Width of the output image.
 183
 184   @param Height Height of the output image.
 185
 186   @param Bitmap Points to the output bitmap.
 187
 188   @param Screen Points to the EFI_GRAPHICS_OUTPUT_PROTOCOL which
 189                 describes the screen on which to draw the
 190                 specified image.
 191
 192 **/
 193 typedef struct _EFI_IMAGE_OUTPUT {
 194   UINT16  Width;
 195   UINT16  Height;
 196   union {
 197     EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Bitmap;
 198     EFI_GRAPHICS_OUTPUT_PROTOCOL  *Screen;
 199   } Image;
 200 } EFI_IMAGE_OUTPUT;
 201
 202
 203 /**
 204
 205   This function renders an image to a bitmap or the screen using
 206   the specified color and options. It draws the image on an
 207   existing bitmap, allocates a new bitmap or uses the screen. The
 208   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
 209   all pixels drawn outside the bounding box specified by Width and
 210   Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT is set,
 211   then all 'off' pixels in the images drawn will use the
 212   pixel value from Blt. This flag cannot be used if Blt is NULL
 213   upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then the image
 214   will be written directly to the output device specified by
 215   Screen. Otherwise the image will be rendered to the bitmap
 216   specified by Bitmap.
 217
 218
 219   @param This       A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 220
 221   @param Flags      Describes how the image is to be drawn.
 222                     EFI_HII_DRAW_FLAGS is defined in Related
 223                     Definitions, below.
 224
 225   @param Image      Points to the image to be displayed.
 226
 227   @param Blt        If this points to a non-NULL on entry, this points
 228                     to the image, which is Width pixels wide and
 229                     Height pixels high. The image will be drawn onto
 230                     this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 231                     If this points to a NULL on entry, then a buffer
 232                     will be allocated to hold the generated image and
 233                     the pointer updated on exit. It is the caller's
 234                     responsibility to free this buffer.
 235
 236   @param BltX, BltY Specifies the offset from the left and top
 237                     edge of the image of the first pixel in
 238                     the image.
 239
 240   @retval EFI_SUCCESS           The image was successfully updated.
 241
 242   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 243                                 buffer for RowInfoArray or Blt.
 244
 245   @retval EFI_INVALID_PARAMETER The Image or Blt or Height or
 246                                 Width was NULL.
 247
 248
 249 **/
 250 typedef
 251 EFI_STATUS
 252 (EFIAPI *EFI_HII_DRAW_IMAGE)(
 253   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 254   IN        EFI_HII_DRAW_FLAGS      Flags,
 255   IN CONST  EFI_IMAGE_INPUT         *Image,
 256   IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 257   IN        UINTN                   BltX,
 258   IN        UINTN                   BltY
 259 );
 260
 261 /**
 262
 263   This function renders an image as a bitmap or to the screen and
 264   can clip the image. The bitmap is either supplied by the caller
 265   or else is allocated by the function. The images can be drawn
 266   transparently or opaquely. If EFI_HII_DRAW_FLAG_CLIP is set,
 267   then all pixels drawn outside the bounding box specified by
 268   Width and Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT
 269   is set, then all "off" pixels in the character's glyph will
 270   use the pixel value from Blt. This flag cannot be used if Blt
 271   is NULL upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then
 272   the image will be written directly to the output device
 273   specified by Screen. Otherwise the image will be rendered to
 274   the bitmap specified by Bitmap.
 275   This function renders an image to a bitmap or the screen using
 276   the specified color and options. It draws the image on an
 277   existing bitmap, allocates a new bitmap or uses the screen. The
 278   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
 279   all pixels drawn outside the bounding box specified by Width and
 280   Height are ignored. The EFI_HII_DRAW_FLAG_TRANSPARENT flag
 281   determines whether the image will be drawn transparent or
 282   opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image
 283   will be drawn so that all 'off' pixels in the image will
 284   be drawn using the pixel value from Blt and all other pixels
 285   will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then
 286   the image's pixels will be copied directly to the
 287   destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image
 288   will be drawn transparently or opaque, depending on the
 289   image's transparency setting (see EFI_IMAGE_TRANSPARENT).
 290   Images cannot be drawn transparently if Blt is NULL. If
 291   EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written
 292   directly to the output device specified by Screen. Otherwise the
 293   image will be rendered to the bitmap specified by Bitmap.
 294
 295   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 296
 297   @param Flags        Describes how the image is to be drawn.
 298
 299   @param PackageList  The package list in the HII database to
 300                       search for the specified image.
 301
 302   @param ImageId      The image's id, which is unique within PackageList.
 303
 304   @param Blt          If this points to a non-NULL on entry, this points
 305                       to the image, which is Width pixels wide and
 306                       Height pixels high. The image will be drawn onto
 307                       this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 308                       If this points to a NULL on entry, then a buffer
 309                       will be allocated to hold the generated image and
 310                       the pointer updated on exit. It is the caller's
 311                       responsibility to free this buffer.
 312
 313   @param BltX, BltY   Specifies the offset from the left and top
 314                       edge of the output image of the first
 315                       pixel in the image.
 316
 317   @retval EFI_SUCCESS           The image was successfully updated.
 318
 319   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 320                                 buffer for RowInfoArray or Blt.
 321
 322   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
 323                                 Or The specified PackageList is not in the database.
 324
 325   @retval EFI_INVALID_PARAMETER The Blt was NULL.
 326
 327 **/
 328 typedef
 329 EFI_STATUS
 330 (EFIAPI *EFI_HII_DRAW_IMAGE_ID)(
 331 IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 332 IN        EFI_HII_DRAW_FLAGS      Flags,
 333 IN        EFI_HII_HANDLE          PackageList,
 334 IN        EFI_IMAGE_ID            ImageId,
 335 IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 336 IN        UINTN                   BltX,
 337 IN        UINTN                   BltY
 338 );
 339
 340
 341 ///
 342 /// Services to access to images in the images database.
 343 ///
 344 struct _EFI_HII_IMAGE_PROTOCOL {
 345   EFI_HII_NEW_IMAGE     NewImage;
 346   EFI_HII_GET_IMAGE     GetImage;
 347   EFI_HII_SET_IMAGE     SetImage;
 348   EFI_HII_DRAW_IMAGE    DrawImage;
 349   EFI_HII_DRAW_IMAGE_ID DrawImageId;
 350 };
 351
 352 extern EFI_GUID gEfiHiiImageProtocolGuid;
 353
 354 #endif
 355
 356