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