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