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