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