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