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