iPXE
HiiImage.h
Go to the documentation of this file.
00001 /** @file
00002   The file provides services to access to images in the images database.
00003 
00004   Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
00005   This program and the accompanying materials
00006   are licensed and made available under the terms and conditions of the BSD License
00007   which accompanies this distribution.  The full text of the license may be found at
00008   http://opensource.org/licenses/bsd-license.php
00009 
00010   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00011   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00012 
00013 **/
00014 
00015 #ifndef __HII_IMAGE_H__
00016 #define __HII_IMAGE_H__
00017 
00018 FILE_LICENCE ( BSD3 );
00019 
00020 #include <ipxe/efi/Protocol/GraphicsOutput.h>
00021 
00022 #define EFI_HII_IMAGE_PROTOCOL_GUID \
00023   { 0x31a6406a, 0x6bdf, 0x4e46, { 0xb2, 0xa2, 0xeb, 0xaa, 0x89, 0xc4, 0x9, 0x20 } }
00024 
00025 typedef struct _EFI_HII_IMAGE_PROTOCOL EFI_HII_IMAGE_PROTOCOL;
00026 
00027 
00028 ///
00029 /// Flags in EFI_IMAGE_INPUT
00030 ///
00031 #define EFI_IMAGE_TRANSPARENT 0x00000001
00032 
00033 /**
00034 
00035   Definition of EFI_IMAGE_INPUT.
00036 
00037   @param Flags  Describe image characteristics. If
00038                 EFI_IMAGE_TRANSPARENT is set, then the image was
00039                 designed for transparent display.
00040 
00041   @param Width  Image width, in pixels.
00042 
00043   @param Height Image height, in pixels.
00044 
00045   @param Bitmap A pointer to the actual bitmap, organized left-to-right,
00046                 top-to-bottom. The size of the bitmap is
00047                 Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL).
00048 
00049 
00050 **/
00051 typedef struct _EFI_IMAGE_INPUT {
00052   UINT32                          Flags;
00053   UINT16                          Width;
00054   UINT16                          Height;
00055   EFI_GRAPHICS_OUTPUT_BLT_PIXEL   *Bitmap;
00056 } EFI_IMAGE_INPUT;
00057 
00058 
00059 /**
00060 
00061   This function adds the image Image to the group of images
00062   owned by PackageList, and returns a new image identifier
00063   (ImageId).
00064 
00065   @param This        A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
00066 
00067   @param PackageList Handle of the package list where this image will be added.
00068 
00069   @param ImageId     On return, contains the new image id, which is
00070                      unique within PackageList.
00071 
00072   @param Image       Points to the image.
00073 
00074   @retval EFI_SUCCESS             The new image was added
00075                                   successfully
00076 
00077   @retval EFI_OUT_OF_RESOURCES    Could not add the image.
00078 
00079   @retval EFI_INVALID_PARAMETER   Image is NULL or ImageId is
00080                                   NULL.
00081 
00082 
00083 **/
00084 typedef
00085 EFI_STATUS
00086 (EFIAPI *EFI_HII_NEW_IMAGE)(
00087   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
00088   IN        EFI_HII_HANDLE          PackageList,
00089   OUT       EFI_IMAGE_ID            *ImageId,
00090   IN CONST  EFI_IMAGE_INPUT         *Image
00091 );
00092 
00093 /**
00094 
00095   This function retrieves the image specified by ImageId which
00096   is associated with the specified PackageList and copies it
00097   into the buffer specified by Image. If the image specified by
00098   ImageId is not present in the specified PackageList, then
00099   EFI_NOT_FOUND is returned. If the buffer specified by
00100   ImageSize is too small to hold the image, then
00101   EFI_BUFFER_TOO_SMALL will be returned. ImageSize will be
00102   updated to the size of buffer actually required to hold the
00103   image.
00104 
00105   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
00106 
00107   @param PackageList  The package list in the HII database to
00108                       search for the specified image.
00109 
00110   @param ImageId      The image's id, which is unique within
00111                       PackageList.
00112 
00113   @param Image        Points to the new image.
00114 
00115   @retval EFI_SUCCESS            The image was returned successfully.
00116 
00117   @retval EFI_NOT_FOUND          The image specified by ImageId is not
00118                                  available. Or The specified PackageList is not in the database.
00119 
00120   @retval EFI_INVALID_PARAMETER  The Image or Langugae was NULL.
00121   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there was not
00122                                  enough memory.
00123 
00124 
00125 **/
00126 typedef
00127 EFI_STATUS
00128 (EFIAPI *EFI_HII_GET_IMAGE)(
00129   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
00130   IN        EFI_HII_HANDLE          PackageList,
00131   IN        EFI_IMAGE_ID            ImageId,
00132   OUT       EFI_IMAGE_INPUT         *Image
00133 );
00134 
00135 /**
00136 
00137   This function updates the image specified by ImageId in the
00138   specified PackageListHandle to the image specified by Image.
00139 
00140 
00141   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
00142 
00143   @param PackageList  The package list containing the images.
00144 
00145   @param ImageId      The image id, which is unique within PackageList.
00146 
00147   @param Image        Points to the image.
00148 
00149   @retval EFI_SUCCESS           The image was successfully updated.
00150 
00151   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
00152                                 The specified PackageList is not in the database.
00153 
00154   @retval EFI_INVALID_PARAMETER The Image or Language was NULL.
00155 
00156 **/
00157 typedef
00158 EFI_STATUS
00159 (EFIAPI *EFI_HII_SET_IMAGE)(
00160   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
00161   IN        EFI_HII_HANDLE          PackageList,
00162   IN        EFI_IMAGE_ID            ImageId,
00163   IN CONST  EFI_IMAGE_INPUT         *Image
00164 );
00165 
00166 
00167 ///
00168 /// EFI_HII_DRAW_FLAGS describes how the image is to be drawn.
00169 /// These flags are defined as EFI_HII_DRAW_FLAG_***
00170 ///
00171 typedef UINT32  EFI_HII_DRAW_FLAGS;
00172 
00173 #define EFI_HII_DRAW_FLAG_CLIP          0x00000001
00174 #define EFI_HII_DRAW_FLAG_TRANSPARENT   0x00000030
00175 #define EFI_HII_DRAW_FLAG_DEFAULT       0x00000000
00176 #define EFI_HII_DRAW_FLAG_FORCE_TRANS   0x00000010
00177 #define EFI_HII_DRAW_FLAG_FORCE_OPAQUE  0x00000020
00178 #define EFI_HII_DIRECT_TO_SCREEN        0x00000080
00179 
00180 /**
00181 
00182   Definition of EFI_IMAGE_OUTPUT.
00183 
00184   @param Width  Width of the output image.
00185 
00186   @param Height Height of the output image.
00187 
00188   @param Bitmap Points to the output bitmap.
00189 
00190   @param Screen Points to the EFI_GRAPHICS_OUTPUT_PROTOCOL which
00191                 describes the screen on which to draw the
00192                 specified image.
00193 
00194 **/
00195 typedef struct _EFI_IMAGE_OUTPUT {
00196   UINT16  Width;
00197   UINT16  Height;
00198   union {
00199     EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Bitmap;
00200     EFI_GRAPHICS_OUTPUT_PROTOCOL  *Screen;
00201   } Image;
00202 } EFI_IMAGE_OUTPUT;
00203 
00204 
00205 /**
00206 
00207   This function renders an image to a bitmap or the screen using
00208   the specified color and options. It draws the image on an
00209   existing bitmap, allocates a new bitmap or uses the screen. The
00210   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
00211   all pixels drawn outside the bounding box specified by Width and
00212   Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT is set,
00213   then all 'off' pixels in the images drawn will use the
00214   pixel value from Blt. This flag cannot be used if Blt is NULL
00215   upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then the image
00216   will be written directly to the output device specified by
00217   Screen. Otherwise the image will be rendered to the bitmap
00218   specified by Bitmap.
00219 
00220 
00221   @param This       A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
00222 
00223   @param Flags      Describes how the image is to be drawn.
00224                     EFI_HII_DRAW_FLAGS is defined in Related
00225                     Definitions, below.
00226 
00227   @param Image      Points to the image to be displayed.
00228 
00229   @param Blt        If this points to a non-NULL on entry, this points
00230                     to the image, which is Width pixels wide and
00231                     Height pixels high. The image will be drawn onto
00232                     this image and EFI_HII_DRAW_FLAG_CLIP is implied.
00233                     If this points to a NULL on entry, then a buffer
00234                     will be allocated to hold the generated image and
00235                     the pointer updated on exit. It is the caller's
00236                     responsibility to free this buffer.
00237 
00238   @param BltX, BltY Specifies the offset from the left and top
00239                     edge of the image of the first pixel in
00240                     the image.
00241 
00242   @retval EFI_SUCCESS           The image was successfully updated.
00243 
00244   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
00245                                 buffer for RowInfoArray or Blt.
00246 
00247   @retval EFI_INVALID_PARAMETER The Image or Blt or Height or
00248                                 Width was NULL.
00249 
00250 
00251 **/
00252 typedef
00253 EFI_STATUS
00254 (EFIAPI *EFI_HII_DRAW_IMAGE)(
00255   IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
00256   IN        EFI_HII_DRAW_FLAGS      Flags,
00257   IN CONST  EFI_IMAGE_INPUT         *Image,
00258   IN OUT    EFI_IMAGE_OUTPUT        **Blt,
00259   IN        UINTN                   BltX,
00260   IN        UINTN                   BltY
00261 );
00262 
00263 /**
00264 
00265   This function renders an image as a bitmap or to the screen and
00266   can clip the image. The bitmap is either supplied by the caller
00267   or else is allocated by the function. The images can be drawn
00268   transparently or opaquely. If EFI_HII_DRAW_FLAG_CLIP is set,
00269   then all pixels drawn outside the bounding box specified by
00270   Width and Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT
00271   is set, then all "off" pixels in the character's glyph will
00272   use the pixel value from Blt. This flag cannot be used if Blt
00273   is NULL upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then
00274   the image will be written directly to the output device
00275   specified by Screen. Otherwise the image will be rendered to
00276   the bitmap specified by Bitmap.
00277   This function renders an image to a bitmap or the screen using
00278   the specified color and options. It draws the image on an
00279   existing bitmap, allocates a new bitmap or uses the screen. The
00280   images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then
00281   all pixels drawn outside the bounding box specified by Width and
00282   Height are ignored. The EFI_HII_DRAW_FLAG_TRANSPARENT flag
00283   determines whether the image will be drawn transparent or
00284   opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image
00285   will be drawn so that all 'off' pixels in the image will
00286   be drawn using the pixel value from Blt and all other pixels
00287   will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then
00288   the image's pixels will be copied directly to the
00289   destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image
00290   will be drawn transparently or opaque, depending on the
00291   image's transparency setting (see EFI_IMAGE_TRANSPARENT).
00292   Images cannot be drawn transparently if Blt is NULL. If
00293   EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written
00294   directly to the output device specified by Screen. Otherwise the
00295   image will be rendered to the bitmap specified by Bitmap.
00296 
00297   @param This         A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
00298 
00299   @param Flags        Describes how the image is to be drawn.
00300 
00301   @param PackageList  The package list in the HII database to
00302                       search for the specified image.
00303 
00304   @param ImageId      The image's id, which is unique within PackageList.
00305 
00306   @param Blt          If this points to a non-NULL on entry, this points
00307                       to the image, which is Width pixels wide and
00308                       Height pixels high. The image will be drawn onto
00309                       this image and EFI_HII_DRAW_FLAG_CLIP is implied.
00310                       If this points to a NULL on entry, then a buffer
00311                       will be allocated to hold the generated image and
00312                       the pointer updated on exit. It is the caller's
00313                       responsibility to free this buffer.
00314 
00315   @param BltX, BltY   Specifies the offset from the left and top
00316                       edge of the output image of the first
00317                       pixel in the image.
00318 
00319   @retval EFI_SUCCESS           The image was successfully updated.
00320 
00321   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
00322                                 buffer for RowInfoArray or Blt.
00323 
00324   @retval EFI_NOT_FOUND         The image specified by ImageId is not in the database.
00325                                 Or The specified PackageList is not in the database.
00326 
00327   @retval EFI_INVALID_PARAMETER The Blt was NULL.
00328 
00329 **/
00330 typedef
00331 EFI_STATUS
00332 (EFIAPI *EFI_HII_DRAW_IMAGE_ID)(
00333 IN CONST  EFI_HII_IMAGE_PROTOCOL  *This,
00334 IN        EFI_HII_DRAW_FLAGS      Flags,
00335 IN        EFI_HII_HANDLE          PackageList,
00336 IN        EFI_IMAGE_ID            ImageId,
00337 IN OUT    EFI_IMAGE_OUTPUT        **Blt,
00338 IN        UINTN                   BltX,
00339 IN        UINTN                   BltY
00340 );
00341 
00342 
00343 ///
00344 /// Services to access to images in the images database.
00345 ///
00346 struct _EFI_HII_IMAGE_PROTOCOL {
00347   EFI_HII_NEW_IMAGE     NewImage;
00348   EFI_HII_GET_IMAGE     GetImage;
00349   EFI_HII_SET_IMAGE     SetImage;
00350   EFI_HII_DRAW_IMAGE    DrawImage;
00351   EFI_HII_DRAW_IMAGE_ID DrawImageId;
00352 };
00353 
00354 extern EFI_GUID gEfiHiiImageProtocolGuid;
00355 
00356 #endif
00357 
00358