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