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