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. All rights reserved.<BR>
   5   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 A pointer to 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 instance.
  62
  63   @param PackageList Handle of the package list 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 instance.
 102
 103   @param PackageList  The package list in the HII database to
 104                       search for the specified image.
 105
 106   @param ImageId      The image's id, which is unique within
 107                       PackageList.
 108
 109   @param Image        Points to the new image.
 110
 111   @retval EFI_SUCCESS            The image was returned successfully.
 112
 113   @retval EFI_NOT_FOUND          The image specified by ImageId is not
 114                                  available. Or The specified PackageList is not in the database.
 115
 116   @retval EFI_INVALID_PARAMETER  The Image or Langugae was NULL.
 117   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there was not
 118                                  enough memory.
 119
 120
 121 **/
 122 typedef
 123 EFI_STATUS
 124 (EFIAPI *EFI_HII_GET_IMAGE)(
 125   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 126   IN        EFI_HII_HANDLE          PackageList,
 127   IN        EFI_IMAGE_ID            ImageId,
 128   OUT       EFI_IMAGE_INPUT         *Image
 129 );
 130
 131 /**
 132
 133   This function updates the image specified by ImageId in the
 134   specified PackageListHandle to the image specified by Image.
 135
 136
 137   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 138
 139   @param PackageList  The package list containing the images.
 140
 141   @param ImageId      The image id, which is unique within PackageList.
 142
 143   @param Image        Points to the image.
 144
 145   @retval EFI_SUCCESS           The image was successfully updated.
 146
 147   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
 148                                 The specified PackageList is not in the database.
 149
 150   @retval EFI_INVALID_PARAMETER The Image or Language was NULL.
 151
 152 **/
 153 typedef
 154 EFI_STATUS
 155 (EFIAPI *EFI_HII_SET_IMAGE)(
 156   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 157   IN        EFI_HII_HANDLE          PackageList,
 158   IN        EFI_IMAGE_ID            ImageId,
 159   IN CONST  EFI_IMAGE_INPUT         *Image
 160 );
 161
 162
 163 ///
 164 /// EFI_HII_DRAW_FLAGS describes how the image is to be drawn.
 165 /// These flags are defined as EFI_HII_DRAW_FLAG_***
 166 ///
 167 typedef UINT32  EFI_HII_DRAW_FLAGS;
 168
 169 #define EFI_HII_DRAW_FLAG_CLIP          0x00000001
 170 #define EFI_HII_DRAW_FLAG_TRANSPARENT   0x00000030
 171 #define EFI_HII_DRAW_FLAG_DEFAULT       0x00000000
 172 #define EFI_HII_DRAW_FLAG_FORCE_TRANS   0x00000010
 173 #define EFI_HII_DRAW_FLAG_FORCE_OPAQUE  0x00000020
 174 #define EFI_HII_DIRECT_TO_SCREEN        0x00000080
 175
 176 /**
 177
 178   Definition of EFI_IMAGE_OUTPUT.
 179
 180   @param Width  Width of the output image.
 181
 182   @param Height Height of the output image.
 183
 184   @param Bitmap Points to the output bitmap.
 185
 186   @param Screen Points to the EFI_GRAPHICS_OUTPUT_PROTOCOL which
 187                 describes the screen on which to draw the
 188                 specified image.
 189
 190 **/
 191 typedef struct _EFI_IMAGE_OUTPUT {
 192   UINT16  Width;
 193   UINT16  Height;
 194   union {
 195     EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Bitmap;
 196     EFI_GRAPHICS_OUTPUT_PROTOCOL  *Screen;
 197   } Image;
 198 } EFI_IMAGE_OUTPUT;
 199
 200
 201 /**
 202
 203   This function renders an image to a bitmap or the screen using
 204   the specified color and options. It draws the image on an
 205   existing bitmap, allocates a new bitmap or uses the screen. The
 206   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
 207   all pixels drawn outside the bounding box specified by Width and
 208   Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT is set,
 209   then all 'off' pixels in the images drawn will use the
 210   pixel value from Blt. This flag cannot be used if Blt is NULL
 211   upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then the image
 212   will be written directly to the output device specified by
 213   Screen. Otherwise the image will be rendered to the bitmap
 214   specified by Bitmap.
 215
 216
 217   @param This       A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 218
 219   @param Flags      Describes how the image is to be drawn.
 220                     EFI_HII_DRAW_FLAGS is defined in Related
 221                     Definitions, below.
 222
 223   @param Image      Points to the image to be displayed.
 224
 225   @param Blt        If this points to a non-NULL on entry, this points
 226                     to the image, which is Width pixels wide and
 227                     Height pixels high. The image will be drawn onto
 228                     this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 229                     If this points to a NULL on entry, then a buffer
 230                     will be allocated to hold the generated image and
 231                     the pointer updated on exit. It is the caller's
 232                     responsibility to free this buffer.
 233
 234   @param BltX, BltY Specifies the offset from the left and top
 235                     edge of the image of the first pixel in
 236                     the image.
 237
 238   @retval EFI_SUCCESS           The image was successfully updated.
 239
 240   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 241                                 buffer for RowInfoArray or Blt.
 242
 243   @retval EFI_INVALID_PARAMETER The Image or Blt or Height or
 244                                 Width was NULL.
 245
 246
 247 **/
 248 typedef
 249 EFI_STATUS
 250 (EFIAPI *EFI_HII_DRAW_IMAGE)(
 251   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 252   IN        EFI_HII_DRAW_FLAGS      Flags,
 253   IN CONST  EFI_IMAGE_INPUT         *Image,
 254   IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 255   IN        UINTN                   BltX,
 256   IN        UINTN                   BltY
 257 );
 258
 259 /**
 260
 261   This function renders an image as a bitmap or to the screen and
 262   can clip the image. The bitmap is either supplied by the caller
 263   or else is allocated by the function. The images can be drawn
 264   transparently or opaquely. If EFI_HII_DRAW_FLAG_CLIP is set,
 265   then all pixels drawn outside the bounding box specified by
 266   Width and Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT
 267   is set, then all "off" pixels in the character's glyph will
 268   use the pixel value from Blt. This flag cannot be used if Blt
 269   is NULL upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then
 270   the image will be written directly to the output device
 271   specified by Screen. Otherwise the image will be rendered to
 272   the bitmap specified by Bitmap.
 273   This function renders an image to a bitmap or the screen using
 274   the specified color and options. It draws the image on an
 275   existing bitmap, allocates a new bitmap or uses the screen. The
 276   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
 277   all pixels drawn outside the bounding box specified by Width and
 278   Height are ignored. The EFI_HII_DRAW_FLAG_TRANSPARENT flag
 279   determines whether the image will be drawn transparent or
 280   opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image
 281   will be drawn so that all 'off' pixels in the image will
 282   be drawn using the pixel value from Blt and all other pixels
 283   will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then
 284   the image's pixels will be copied directly to the
 285   destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image
 286   will be drawn transparently or opaque, depending on the
 287   image's transparency setting (see EFI_IMAGE_TRANSPARENT).
 288   Images cannot be drawn transparently if Blt is NULL. If
 289   EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written
 290   directly to the output device specified by Screen. Otherwise the
 291   image will be rendered to the bitmap specified by Bitmap.
 292
 293   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 294
 295   @param Flags        Describes how the image is to be drawn.
 296
 297   @param PackageList  The package list in the HII database to
 298                       search for the specified image.
 299
 300   @param ImageId      The image's id, which is unique within PackageList.
 301
 302   @param Blt          If this points to a non-NULL on entry, this points
 303                       to the image, which is Width pixels wide and
 304                       Height pixels high. The image will be drawn onto
 305                       this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 306                       If this points to a NULL on entry, then a buffer
 307                       will be allocated to hold the generated image and
 308                       the pointer updated on exit. It is the caller's
 309                       responsibility to free this buffer.
 310
 311   @param BltX, BltY   Specifies the offset from the left and top
 312                       edge of the output image of the first
 313                       pixel in the image.
 314
 315   @retval EFI_SUCCESS           The image was successfully updated.
 316
 317   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 318                                 buffer for RowInfoArray or Blt.
 319
 320   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
 321                                 Or The specified PackageList is not in the database.
 322
 323   @retval EFI_INVALID_PARAMETER The Blt was NULL.
 324
 325 **/
 326 typedef
 327 EFI_STATUS
 328 (EFIAPI *EFI_HII_DRAW_IMAGE_ID)(
 329 IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
 330 IN        EFI_HII_DRAW_FLAGS      Flags,
 331 IN        EFI_HII_HANDLE          PackageList,
 332 IN        EFI_IMAGE_ID            ImageId,
 333 IN OUT    EFI_IMAGE_OUTPUT        **Blt,
 334 IN        UINTN                   BltX,
 335 IN        UINTN                   BltY
 336 );
 337
 338
 339 ///
 340 /// Services to access to images in the images database.
 341 ///
 342 struct _EFI_HII_IMAGE_PROTOCOL {
 343   EFI_HII_NEW_IMAGE     NewImage;
 344   EFI_HII_GET_IMAGE     GetImage;
 345   EFI_HII_SET_IMAGE     SetImage;
 346   EFI_HII_DRAW_IMAGE    DrawImage;
 347   EFI_HII_DRAW_IMAGE_ID DrawImageId;
 348 };
 349
 350 extern EFI_GUID gEfiHiiImageProtocolGuid;
 351
 352 #endif
 353
 354