====== Configure graphical console ======

===== Synopsis =====

    console [--x <width>] [--y <height>]
            [--left <left margin>] [--right <right margin>]
            [--top <top margin>] [--bottom <bottom margin>]
            [--depth <colour depth>]
            [--picture <background picture>] [--keep]

===== Examples =====

=== Resize the console to 1024x768 ===

    console --x 1024 --y 768

=== Set a background picture ===

    console --picture http://boot.ipxe.org/ipxe.png

=== Set a background picture with margins ===

    console --picture http://boot.ipxe.org/texture.png --left 32 --right 32 --top 32 --bottom 48

=== Reset the console (and clear the screen) ===

    console

===== Description =====

Configure the console with the specified width, height, margins, colour depth, and background picture.  All distances are specified in pixels.  The width, height, and colour depth are specified as minimum requirements; the actual values used may be higher than specified.  If a background picture is used then the width and height may be omitted; the console size will then be chosen based on the size of the background picture.

The background picture will be discarded after configuring the console unless the ''%%--keep%%'' option is specified.

Any non-zero margins are treated as being relative to the specified minimum width and height.

{{ :screenshots:background.png?400x300 |A sample background picture}}

===== Command status =====

^ Success   | The console was successfully configured          |
^ Failure   | The console was not successfully configured      |

===== See also =====

  * ''[[:cmd:colour]]''
  * ''[[:cmd:cpair]]''
  * [[:console|Console configuration]] in iPXE
  * [[:cmd|List of all iPXE commands]]

===== Build options =====

This command is available only when the build option ''[[:buildcfg:CONSOLE_CMD]]'' is enabled.

Support for graphical consoles is available only when the relevant build options (e.g. ''[[:buildcfg:CONSOLE_FRAMEBUFFER]]'' for the graphical framebuffer console) are enabled.

Support for background pictures is available only when the relevant build options (e.g. ''[[:buildcfg:IMAGE_PNG]]'' for PNG images) are enabled.

===== Notes =====

You can use the ''console'' command (with no options) to reset the console and clear the screen.

To select the graphical framebuffer console you must either specify a width and height, or specify a background picture.

You can use the margins to define a text area within a background picture.  For example, you could place your company logo in the top right corner, and specify a top margin to ensure that iPXE's text does not overwrite your logo.

You can use the ''[[:cmd:colour]]'' and ''[[:cmd:cpair]]'' commands to change the text colour scheme to match your background picture.

You can use the ''%%--keep%%'' option if you intend to reuse the same background image in a future ''console'' command, to avoid downloading the image a second time.