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 - 2008, 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;
  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   @retval EFI_SUCCESS   The image was returned successfully.
 113                                      The specified PackageList is not in the database.
 114   @retval EFI_NOT_FOUND The image specified by ImageId is not
 115                         available.
 116
 117   @retval EFI_INVALID_PARAMETER The Image or Langugae was NULL.
 118   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there was not
 119                          enough memory.
 120
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EFI_HII_GET_IMAGE) (
 126   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 127   IN        EFI_HII_HANDLE          PackageList,
 128   IN        EFI_IMAGE_ID            ImageId,
 129   OUT       EFI_IMAGE_INPUT         *Image
 130 );
 131
 132 /**
 133
 134   This function updates the image specified by ImageId in the
 135   specified PackageListHandle to the image specified by Image.
 136
 137
 138   @param This   A pointer to the EFI_HII_IMAGE_PROTOCOL
 139                 instance.
 140
 141   @param PackageList  The package list containing the images.
 142
 143   @param ImageId  The image id, which is unique within
 144                   PackageList.
 145
 146   @param Image  Points to the image.
 147
 148   @retval EFI_SUCCESS The image was successfully updated.
 149
 150   @retval EFI_NOT_FOUND   The image specified by ImageId is not
 151                                         in the database.
 152                                         The specified PackageList is not in the database.
 153
 154   @retval EFI_INVALID_PARAMETER   The Image or Language was
 155                                   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
 170 //
 171 typedef UINT32  EFI_HII_DRAW_FLAGS;
 172
 173 #define EFI_HII_DRAW_FLAG_CLIP          0x00000001
 174 #define EFI_HII_DRAW_FLAG_TRANSPARENT   0x00000030
 175 #define EFI_HII_DRAW_FLAG_DEFAULT       0x00000000
 176 #define EFI_HII_DRAW_FLAG_FORCE_TRANS   0x00000010
 177 #define EFI_HII_DRAW_FLAG_FORCE_OPAQUE  0x00000020
 178 #define EFI_HII_DIRECT_TO_SCREEN        0x00000080
 179
 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
 223                 instance.
 224
 225   @param Flags  Describes how the image is to be drawn.
 226                 EFI_HII_DRAW_FLAGS is defined in Related
 227                 Definitions, below.
 228
 229   @param Image  Points to the image to be displayed.
 230
 231   @param Blt  If this points to a non-NULL on entry, this points
 232               to the image, which is Width pixels wide and
 233               Height pixels high. The image will be drawn onto
 234               this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 235               If this points to a NULL on entry, then a buffer
 236               will be allocated to hold the generated image and
 237               the pointer updated on exit. It is the caller????s
 238               responsibility to free this buffer.
 239
 240   @param BltX, BltY   Specifies the offset from the left and top
 241                       edge of the image of the first pixel in
 242                       the image.
 243
 244   @retval EFI_SUCCESS   The image was successfully updated.
 245
 246   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 247                                 buffer for RowInfoArray or Blt.
 248
 249   @retval EFI_INVALID_PARAMETER The Image or Blt or Height or
 250                                 Width was NULL.
 251
 252
 253 **/
 254 typedef
 255 EFI_STATUS
 256 (EFIAPI *EFI_HII_DRAW_IMAGE) (
 257   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 258   IN        EFI_HII_DRAW_FLAGS      Flags,
 259   IN CONST  EFI_IMAGE_INPUT         *Image,
 260   IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 261   IN        UINTN                   BltX,
 262   IN        UINTN                   BltY
 263 );
 264
 265 /**
 266
 267   This function renders an image as a bitmap or to the screen and
 268   can clip the image. The bitmap is either supplied by the caller
 269   or else is allocated by the function. The images can be drawn
 270   transparently or opaquely. If EFI_HII_DRAW_FLAG_CLIP is set,
 271   then all pixels drawn outside the bounding box specified by
 272   Width and Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT
 273   is set, then all "off" pixels in the character's glyph will
 274   use the pixel value from Blt. This flag cannot be used if Blt
 275   is NULL upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then
 276   the image will be written directly to the output device
 277   specified by Screen. Otherwise the image will be rendered to
 278   the bitmap specified by Bitmap.
 279   This function renders an image to a bitmap or the screen using
 280   the specified color and options. It draws the image on an
 281   existing bitmap, allocates a new bitmap or uses the screen. The
 282   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
 283   all pixels drawn outside the bounding box specified by Width and
 284   Height are ignored. The EFI_HII_DRAW_FLAG_TRANSPARENT flag
 285   determines whether the image will be drawn transparent or
 286   opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image
 287   will be drawn so that all ????off???? pixels in the image will
 288   be drawn using the pixel value from Blt and all other pixels
 289   will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then
 290   the image????s pixels will be copied directly to the
 291   destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image
 292   will be drawn transparently or opaque, depending on the
 293   image????s transparency setting (see EFI_IMAGE_TRANSPARENT).
 294   Images cannot be drawn transparently if Blt is NULL. If
 295   EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written
 296   directly to the output device specified by Screen. Otherwise the
 297   image will be rendered to the bitmap specified by Bitmap.
 298
 299   @param This   A pointer to the EFI_HII_IMAGE_PROTOCOL
 300                 instance.
 301
 302   @param Flags  Describes how the image is to be drawn.
 303
 304   @param PackageList  The package list in the HII database to
 305                       search for the specified image.
 306
 307   @param ImageId  The image's id, which is unique within
 308                   PackageList.
 309
 310   @param Blt  If this points to a non-NULL on entry, this points
 311               to the image, which is Width pixels wide and
 312               Height pixels high. The image will be drawn onto
 313               this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 314               If this points to a NULL on entry, then a buffer
 315               will be allocated to hold the generated image and
 316               the pointer updated on exit. It is the caller's
 317               responsibility to free this buffer.
 318
 319   @param BltX, BltY   Specifies the offset from the left and top
 320                       edge of the output image of the first
 321                       pixel in the image.
 322
 323   @retval EFI_SUCCESS   The image was successfully updated.
 324
 325   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 326                                 buffer for RowInfoArray or Blt.
 327
 328   @retval EFI_NOT_FOUND  The image specified by ImageId is not in the database.
 329                                         The specified PackageList is not in the database.
 330   @retval EFI_INVALID_PARAMETER  The Blt was NULL.
 331
 332 **/
 333 typedef
 334 EFI_STATUS
 335 (EFIAPI *EFI_HII_DRAW_IMAGE_ID) (
 336 IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 337 IN        EFI_HII_DRAW_FLAGS      Flags,
 338 IN        EFI_HII_HANDLE          PackageList,
 339 IN        EFI_IMAGE_ID            ImageId,
 340 IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 341 IN        UINTN                   BltX,
 342 IN        UINTN                   BltY
 343 );
 344
 345
 346 /**
 347
 348   services to access to images in the images database.
 349
 350   @param NewImage   Add a new image.
 351
 352   @param GetImage   Retrieve an image and related font
 353                     information.
 354
 355   @param SetImage   Change an image. EFI_INVALID_LANGUAGE The
 356                     language specified by FirstLanguage is not
 357                     present in the specified package list.
 358                     EFI_INVALID_PARAMETER FirstLanguage is NULL
 359                     or SecondLanguage is NULL.
 360
 361 **/
 362 struct _EFI_HII_IMAGE_PROTOCOL {
 363   EFI_HII_NEW_IMAGE     NewImage;
 364   EFI_HII_GET_IMAGE     GetImage;
 365   EFI_HII_SET_IMAGE     SetImage;
 366   EFI_HII_DRAW_IMAGE    DrawImage;
 367   EFI_HII_DRAW_IMAGE_ID DrawImageId;
 368 };
 369
 370 extern EFI_GUID gEfiHiiImageProtocolGuid;
 371
 372 #endif
 373
 374