Graphics

Graphics

Command Index · BlitzBasic · Display

Graphics:Void width:Int32, height:Int32, depth:Int32=0, mode:Int32=0

Parameter	Mode	Type	Default	Description
width	In	Int32	required	Width of the picture in pixels.
height	In	Int32	required	Height of the picture in pixels.
depth	In	Int32	0	Color depth in bits, see Color depth above: 8, 12, 15, 16, 24, 30, 32 or 64, or 0 for 32. Defaults to 0.
mode	In	Int32	0	0 opens a window, 1 uses full screen (a borderless window over the display, see Full screen above), 2 opens a window and 3 opens a window that the user can resize. 4 opens a window without a border: no title bar and no frame. Mode 4 is a BlitzLLVM extension that original Blitz does not have. Defaults to 0.

Description

Opens the graphics window and has to be called before any drawing command. Calling it again closes the window and opens a new one, and then all images and textures are gone, so load them again. It also puts the colors and the current buffer back to their defaults.

Differences

• Graphics is the same command as Graphics3D: there is no 2D-only mode, so the 3D commands work after Graphics as well.
• The depth picks the format of the buffers and not a display mode, and the 8 bit mode has a palette. See Color depth above.
• Full screen (mode 1) does not change the video mode of the display, see Full screen above.
• In a resizable window (mode 3) the picture is scaled to the size of the window, and the mouse position is converted to picture pixels.
• The modes 6 and 7 of Blitz3D, which pause the program while the window is in the background, act like 2 and 3. The program keeps running.
• A window without a border (mode 4) has the size you ask for and cannot be resized by the user.
• A width or height below 1 stops the program with an error message.

Examples

Graphics 320, 240, 32, 2
SetBuffer BackBuffer()
Cls
Text 160, 100, "Graphics 320, 240, 32, 2", 1, 1
Text 160, 120, "Width " + GraphicsWidth() + ", Height " + GraphicsHeight(), 1, 1
Flip
WaitKey

Color depth

The depth argument is not a display mode: it picks what the buffers are made of, so that many faint layers drawn over each other do not lose their small steps to rounding. The window always shows 8 bits per channel.

Depth	Buffer
0	Same as 32.
8	A palette of 256 colors, set with GraphicsPalette.
12	R4G4B4A4.
15	A1R5G5B5.
16	R5G6B5, no alpha.
24	R8G8B8, no alpha.
30	R10G10B10A2.
32	R8G8B8A8.
64	R16G16B16A16 as half precision floats (values above 1 are kept).

Any other number gives 32 with a warning. If the graphics card can't draw to a format, the next smaller one in the table is used and a warning says so. GraphicsDepth tells you which you got.

GfxModeDepth, DisplayDepth and DisplayModeDepth always say 32, and WBuffer does nothing.

Pixel commands (ReadPixel, WritePixel, the Fast and CopyPixel versions) take and give ARGB with 8 bits per channel for every depth, except 30, which uses A2R10G10B10. Depths 8, 12, 15 and 16 are widened to 8 bits per channel, and what you write is rounded to the nearest value the buffer can hold. For depth 64, ReadPixel64 and WritePixel64 work with the half float channels as they are. Textures and images are always RGBA8, and SaveBuffer, GrabImage and CopyRect convert on the way.

Dither adds noise of one step of the buffer before rounding, which hides banding. The same scene with the depths 32, 16, 15, 12 and 8, without and with Dither:

Depth 30 or 64 matters most for soft mist or smoke made of many overlapping, nearly transparent sprites: with 8 bits every blend rounds, and contour lines show where a faint layer changes nothing. Depth 30 stayed within half a step of the exact result in tests, so it is the first choice for such scenes. Dither does not help in a depth 32 buffer, because it dithers before the blend rounds again.

Full screen

Mode 1 does not change the video mode of the display. It opens a borderless window over the main display and shows the picture in it at the largest size that fits with its aspect ratio kept, centered, with black bars for the rest (a 4:3 picture on a 16:9 display has them left and right). Alt-Tab is instant and the desktop is not rearranged. Any size is allowed, so GfxModeExists and GfxMode3DExists do not matter for the window.

• The program only sees the picture: GraphicsWidth, GraphicsHeight, ReadPixel, GrabImage and SaveBuffer never include the bars or the size of the display. The mouse commands and the BlitzPlus gadgets and dialogs use the coordinates of the picture, and over a bar the mouse is at the nearest edge of it. A picture larger than the display is made smaller to fit.
• A picture whose size is a whole number times the size you asked for is not smoothed, so pixel art stays sharp. Other sizes are smoothed.
• BLITZLLVM_FULLSCREEN_FILTER=nearest or linear chooses.
• BLITZLLVM_FULLSCREEN_SCALE=integer only enlarges by whole numbers, with larger bars.
• The other modes are not changed; a resizable window (mode 3) still scales the picture to the whole window.

Windows and DPI

Programs on Windows are DPI aware. Windows does not scale their window, so one pixel of the program is one pixel of the screen at any scaling, and GraphicsWidth, the mouse and the display modes are physical pixels. The original has no manifest, so Windows stretches its windows and makes them blurry at 150 %.

blitzcc embeds a manifest for this. A program built with its own .res or manifest (--llvm-flag) keeps that one instead.

The windows of BlitzPlus are scaled, see Windows of BlitzPlus.

Media

Related Commands

EndGraphics, GraphicsDepth, GraphicsFormat, GraphicsHeight, GraphicsLost, GraphicsPalette, GraphicsWidth

Command Index · BlitzBasic · Display