iPXE
HiiImage.h
Go to the documentation of this file.
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 
21 
22 #define EFI_HII_IMAGE_PROTOCOL_GUID \
23  { 0x31a6406a, 0x6bdf, 0x4e46, { 0xb2, 0xa2, 0xeb, 0xaa, 0x89, 0xc4, 0x9, 0x20 } }
24 
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 {
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
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
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
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 ///
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 {
198  union {
201  } Image;
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
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
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 ///
352 };
353 
355 
356 #endif
357 
358 
Definition of EFI_IMAGE_INPUT.
Definition: HiiImage.h:51
UINT16 Height
Definition: HiiImage.h:54
struct _EFI_IMAGE_OUTPUT EFI_IMAGE_OUTPUT
Definition of EFI_IMAGE_OUTPUT.
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
EFI_HII_NEW_IMAGE NewImage
Definition: HiiImage.h:347
EFI_HII_SET_IMAGE SetImage
Definition: HiiImage.h:349
unsigned int UINT32
Definition: ProcessorBind.h:56
EFI_GRAPHICS_OUTPUT_BLT_PIXEL * Bitmap
Definition: HiiImage.h:55
struct _EFI_IMAGE_INPUT EFI_IMAGE_INPUT
Definition of EFI_IMAGE_INPUT.
EFI_GRAPHICS_OUTPUT_BLT_PIXEL * Bitmap
Definition: HiiImage.h:199
UINT16_t Flags
Flags.
Definition: pxe_api.h:87
EFI_STATUS(EFIAPI * EFI_HII_NEW_IMAGE)(IN CONST EFI_HII_IMAGE_PROTOCOL *This, IN EFI_HII_HANDLE PackageList, OUT EFI_IMAGE_ID *ImageId, IN CONST EFI_IMAGE_INPUT *Image)
This function adds the image Image to the group of images owned by PackageList, and returns a new ima...
Definition: HiiImage.h:86
Provides a basic abstraction to set video modes and copy pixels to and from the graphics controller's...
#define OUT
Definition: mlx_utils.h:29
EFI_STATUS(EFIAPI * EFI_HII_GET_IMAGE)(IN CONST EFI_HII_IMAGE_PROTOCOL *This, IN EFI_HII_HANDLE PackageList, IN EFI_IMAGE_ID ImageId, OUT EFI_IMAGE_INPUT *Image)
This function retrieves the image specified by ImageId which is associated with the specified Package...
Definition: HiiImage.h:128
UINT32 Flags
Definition: HiiImage.h:52
unsigned short UINT16
Definition: ProcessorBind.h:58
#define EFIAPI
UINT64 UINTN
Unsigned value of native width.
Definition: ProcessorBind.h:71
UINT32 EFI_HII_DRAW_FLAGS
EFI_HII_DRAW_FLAGS describes how the image is to be drawn.
Definition: HiiImage.h:171
EFI_HII_GET_IMAGE GetImage
Definition: HiiImage.h:348
#define IN
Definition: mlx_utils.h:28
Graphics Output Protocol from the UEFI 2.0 specification.
Services to access to images in the images database.
Definition: HiiImage.h:346
EFI_GUID gEfiHiiImageProtocolGuid
#define CONST
Datum is read-only.
Definition: Base.h:309
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
union _EFI_IMAGE_OUTPUT::@496 Image
EFI_STATUS(EFIAPI * EFI_HII_DRAW_IMAGE)(IN CONST EFI_HII_IMAGE_PROTOCOL *This, IN EFI_HII_DRAW_FLAGS Flags, IN CONST EFI_IMAGE_INPUT *Image, IN OUT EFI_IMAGE_OUTPUT **Blt, IN UINTN BltX, IN UINTN BltY)
This function renders an image to a bitmap or the screen using the specified color and options.
Definition: HiiImage.h:254
FILE_LICENCE(BSD3)
EFI_GRAPHICS_OUTPUT_PROTOCOL * Screen
Definition: HiiImage.h:200
EFI_STATUS(EFIAPI * EFI_HII_SET_IMAGE)(IN CONST EFI_HII_IMAGE_PROTOCOL *This, IN EFI_HII_HANDLE PackageList, IN EFI_IMAGE_ID ImageId, IN CONST EFI_IMAGE_INPUT *Image)
This function updates the image specified by ImageId in the specified PackageListHandle to the image ...
Definition: HiiImage.h:159
EFI_STATUS(EFIAPI * EFI_HII_DRAW_IMAGE_ID)(IN CONST EFI_HII_IMAGE_PROTOCOL *This, IN EFI_HII_DRAW_FLAGS Flags, IN EFI_HII_HANDLE PackageList, IN EFI_IMAGE_ID ImageId, IN OUT EFI_IMAGE_OUTPUT **Blt, IN UINTN BltX, IN UINTN BltY)
This function renders an image as a bitmap or to the screen and can clip the image.
Definition: HiiImage.h:332
Definition of EFI_IMAGE_OUTPUT.
Definition: HiiImage.h:195
VOID * EFI_HII_HANDLE
The following types are currently defined:
EFI_HII_DRAW_IMAGE_ID DrawImageId
Definition: HiiImage.h:351
EFI_HII_DRAW_IMAGE DrawImage
Definition: HiiImage.h:350
UINT16 Width
Definition: HiiImage.h:53