MdePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdePkg / Include / Protocol / GraphicsOutput.h

/** @file\r
  Graphics Output Protocol from the UEFI 2.0 specification.\r
\r
  Abstraction of a very simple graphics device.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __GRAPHICS_OUTPUT_H__\r
#define __GRAPHICS_OUTPUT_H__\r
\r
#define EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID \\r
  { \\r
    0x9042a9de, 0x23dc, 0x4a38, {0x96, 0xfb, 0x7a, 0xde, 0xd0, 0x80, 0x51, 0x6a } \\r
  }\r
\r
typedef struct _EFI_GRAPHICS_OUTPUT_PROTOCOL EFI_GRAPHICS_OUTPUT_PROTOCOL;\r
\r
typedef struct {\r
  UINT32            RedMask;\r
  UINT32            GreenMask;\r
  UINT32            BlueMask;\r
  UINT32            ReservedMask;\r
} EFI_PIXEL_BITMASK;\r
\r
typedef enum {\r
  ///\r
  /// A pixel is 32-bits and byte zero represents red, byte one represents green,\r
  /// byte two represents blue, and byte three is reserved. This is the definition\r
  /// for the physical frame buffer. The byte values for the red, green, and blue\r
  /// components represent the color intensity. This color intensity value range\r
  /// from a minimum intensity of 0 to maximum intensity of 255.\r
  ///\r
  PixelRedGreenBlueReserved8BitPerColor,\r
  ///\r
  /// A pixel is 32-bits and byte zero represents blue, byte one represents green,\r
  /// byte two represents red, and byte three is reserved. This is the definition\r
  /// for the physical frame buffer. The byte values for the red, green, and blue\r
  /// components represent the color intensity. This color intensity value range\r
  /// from a minimum intensity of 0 to maximum intensity of 255.\r
  ///\r
  PixelBlueGreenRedReserved8BitPerColor,\r
  ///\r
  /// The Pixel definition of the physical frame buffer.\r
  ///\r
  PixelBitMask,\r
  ///\r
  /// This mode does not support a physical frame buffer.\r
  ///\r
  PixelBltOnly,\r
  ///\r
  /// Valid EFI_GRAPHICS_PIXEL_FORMAT enum values are less than this value.\r
  ///\r
  PixelFormatMax\r
} EFI_GRAPHICS_PIXEL_FORMAT;\r
\r
typedef struct {\r
  ///\r
  /// The version of this data structure. A value of zero represents the\r
  /// EFI_GRAPHICS_OUTPUT_MODE_INFORMATION structure as defined in this specification.\r
  ///\r
  UINT32                     Version;\r
  ///\r
  /// The size of video screen in pixels in the X dimension.\r
  ///\r
  UINT32                     HorizontalResolution;\r
  ///\r
  /// The size of video screen in pixels in the Y dimension.\r
  ///\r
  UINT32                     VerticalResolution;\r
  ///\r
  /// Enumeration that defines the physical format of the pixel. A value of PixelBltOnly\r
  /// implies that a linear frame buffer is not available for this mode.\r
  ///\r
  EFI_GRAPHICS_PIXEL_FORMAT  PixelFormat;\r
  ///\r
  /// This bit-mask is only valid if PixelFormat is set to PixelPixelBitMask.\r
  /// A bit being set defines what bits are used for what purpose such as Red, Green, Blue, or Reserved.\r
  ///\r
  EFI_PIXEL_BITMASK          PixelInformation;\r
  ///\r
  /// Defines the number of pixel elements per video memory line.\r
  ///\r
  UINT32                     PixelsPerScanLine;\r
} EFI_GRAPHICS_OUTPUT_MODE_INFORMATION;\r
\r
/**\r
  Returns information for an available graphics mode that the graphics device\r
  and the set of active video output devices supports.\r
\r
  @param  This                  The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.\r
  @param  ModeNumber            The mode number to return information on.\r
  @param  SizeOfInfo            A pointer to the size, in bytes, of the Info buffer.\r
  @param  Info                  A pointer to callee allocated buffer that returns information about ModeNumber.\r
\r
  @retval EFI_SUCCESS           Valid mode information was returned.\r
  @retval EFI_DEVICE_ERROR      A hardware error occurred trying to retrieve the video mode.\r
  @retval EFI_INVALID_PARAMETER ModeNumber is not valid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE)(\r
  IN  EFI_GRAPHICS_OUTPUT_PROTOCOL          *This,\r
  IN  UINT32                                ModeNumber,\r
  OUT UINTN                                 *SizeOfInfo,\r
  OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION  **Info\r
  );\r
\r
/**\r
  Set the video device into the specified mode and clears the visible portions of\r
  the output display to black.\r
\r
  @param  This              The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.\r
  @param  ModeNumber        Abstraction that defines the current video mode.\r
\r
  @retval EFI_SUCCESS       The graphics mode specified by ModeNumber was selected.\r
  @retval EFI_DEVICE_ERROR  The device had an error and could not complete the request.\r
  @retval EFI_UNSUPPORTED   ModeNumber is not supported by this device.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE)(\r
  IN  EFI_GRAPHICS_OUTPUT_PROTOCOL *This,\r
  IN  UINT32                       ModeNumber\r
  );\r
\r
typedef struct {\r
  UINT8 Blue;\r
  UINT8 Green;\r
  UINT8 Red;\r
  UINT8 Reserved;\r
} EFI_GRAPHICS_OUTPUT_BLT_PIXEL;\r
\r
typedef union {\r
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL Pixel;\r
  UINT32                        Raw;\r
} EFI_GRAPHICS_OUTPUT_BLT_PIXEL_UNION;\r
\r
///\r
/// actions for BltOperations\r
///\r
typedef enum {\r
  ///\r
  /// Write data from the BltBuffer pixel (0, 0)\r
  /// directly to every pixel of the video display rectangle\r
  /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height).\r
  /// Only one pixel will be used from the BltBuffer. Delta is NOT used.\r
  ///\r
  EfiBltVideoFill,\r
\r
  ///\r
  /// Read data from the video display rectangle\r
  /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) and place it in\r
  /// the BltBuffer rectangle (DestinationX, DestinationY )\r
  /// (DestinationX + Width, DestinationY + Height). If DestinationX or\r
  /// DestinationY is not zero then Delta must be set to the length in bytes\r
  /// of a row in the BltBuffer.\r
  ///\r
  EfiBltVideoToBltBuffer,\r
\r
  ///\r
  /// Write data from the BltBuffer rectangle\r
  /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) directly to the\r
  /// video display rectangle (DestinationX, DestinationY)\r
  /// (DestinationX + Width, DestinationY + Height). If SourceX or SourceY is\r
  /// not zero then Delta must be set to the length in bytes of a row in the\r
  /// BltBuffer.\r
  ///\r
  EfiBltBufferToVideo,\r
\r
  ///\r
  /// Copy from the video display rectangle (SourceX, SourceY)\r
  /// (SourceX + Width, SourceY + Height) to the video display rectangle\r
  /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height).\r
  /// The BltBuffer and Delta are not used in this mode.\r
  ///\r
  EfiBltVideoToVideo,\r
\r
  EfiGraphicsOutputBltOperationMax\r
} EFI_GRAPHICS_OUTPUT_BLT_OPERATION;\r
\r
/**\r
  Blt a rectangle of pixels on the graphics screen. Blt stands for BLock Transfer.\r
\r
  @param  This         Protocol instance pointer.\r
  @param  BltBuffer    The data to transfer to the graphics screen.\r
                       Size is at least Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL).\r
  @param  BltOperation The operation to perform when copying BltBuffer on to the graphics screen.\r
  @param  SourceX      The X coordinate of source for the BltOperation.\r
  @param  SourceY      The Y coordinate of source for the BltOperation.\r
  @param  DestinationX The X coordinate of destination for the BltOperation.\r
  @param  DestinationY The Y coordinate of destination for the BltOperation.\r
  @param  Width        The width of a rectangle in the blt rectangle in pixels.\r
  @param  Height       The height of a rectangle in the blt rectangle in pixels.\r
  @param  Delta        Not used for EfiBltVideoFill or the EfiBltVideoToVideo operation.\r
                       If a Delta of zero is used, the entire BltBuffer is being operated on.\r
                       If a subrectangle of the BltBuffer is being used then Delta\r
                       represents the number of bytes in a row of the BltBuffer.\r
\r
  @retval EFI_SUCCESS           BltBuffer was drawn to the graphics screen.\r
  @retval EFI_INVALID_PARAMETER BltOperation is not valid.\r
  @retval EFI_DEVICE_ERROR      The device had an error and could not complete the request.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT)(\r
  IN  EFI_GRAPHICS_OUTPUT_PROTOCOL            *This,\r
  IN  EFI_GRAPHICS_OUTPUT_BLT_PIXEL           *BltBuffer,   OPTIONAL\r
  IN  EFI_GRAPHICS_OUTPUT_BLT_OPERATION       BltOperation,\r
  IN  UINTN                                   SourceX,\r
  IN  UINTN                                   SourceY,\r
  IN  UINTN                                   DestinationX,\r
  IN  UINTN                                   DestinationY,\r
  IN  UINTN                                   Width,\r
  IN  UINTN                                   Height,\r
  IN  UINTN                                   Delta         OPTIONAL\r
  );\r
\r
typedef struct {\r
  ///\r
  /// The number of modes supported by QueryMode() and SetMode().\r
  ///\r
  UINT32                                 MaxMode;\r
  ///\r
  /// Current Mode of the graphics device. Valid mode numbers are 0 to MaxMode -1.\r
  ///\r
  UINT32                                 Mode;\r
  ///\r
  /// Pointer to read-only EFI_GRAPHICS_OUTPUT_MODE_INFORMATION data.\r
  ///\r
  EFI_GRAPHICS_OUTPUT_MODE_INFORMATION   *Info;\r
  ///\r
  /// Size of Info structure in bytes.\r
  ///\r
  UINTN                                  SizeOfInfo;\r
  ///\r
  /// Base address of graphics linear frame buffer.\r
  /// Offset zero in FrameBufferBase represents the upper left pixel of the display.\r
  ///\r
  EFI_PHYSICAL_ADDRESS                   FrameBufferBase;\r
  ///\r
  /// Amount of frame buffer needed to support the active mode as defined by\r
  /// PixelsPerScanLine xVerticalResolution x PixelElementSize.\r
  ///\r
  UINTN                                  FrameBufferSize;\r
} EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE;\r
\r
///\r
/// Provides a basic abstraction to set video modes and copy pixels to and from\r
/// the graphics controller's frame buffer. The linear address of the hardware\r
/// frame buffer is also exposed so software can write directly to the video hardware.\r
///\r
struct _EFI_GRAPHICS_OUTPUT_PROTOCOL {\r
  EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE  QueryMode;\r
  EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE    SetMode;\r
  EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT         Blt;\r
  ///\r
  /// Pointer to EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE data.\r
  ///\r
  EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE        *Mode;\r
};\r
\r
extern EFI_GUID gEfiGraphicsOutputProtocolGuid;\r
\r
#endif\r