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