zscript-doc/api/drawing/Screen.md

Screen

Functions for drawing various things to the screen.

Note: There are no longer any fully paletted renderers in GZDoom as of version 3.5. Alternate palette index parameters are generally ignored now.

struct Screen
{
   static vararg void DrawChar(Font font, int cr, double x, double y, int character, ...);
   static vararg void DrawShape(textureid tex, bool animate, Shape2D s, ...);
   static vararg void DrawText(Font font, int cr, double x, double y, string text, ...);
   static vararg void DrawTexture(textureid tex, bool animate, double x, double y, ...);

   static void Clear(int left, int top, int right, int bottom, color cr, int palcolor = -1);
   static void Dim(color cr, double amount, int x, int y, int w, int h);
   static void DrawFrame(int x, int y, int w, int h);
   static void DrawLine(int x0, int y0, int x1, int y1, color cr, int alpha = 255);
   static void DrawThickLine(int x0, int y0, int x1, int y1, double thickness, color cr, int alpha = 255);

   static double GetAspectRatio();
   static int GetHeight();
   static int GetWidth();
   static color PaletteColor(int index);
   static vector2, vector2 VirtualToRealCoords(vector2 pos, vector2 size, vector2 vsize, bool vbottom = false, bool handleaspect = true);

   static void ClearClipRect();
   static int, int, int, int GetClipRect();
   static int, int, int, int GetViewWindow();
   static void SetClipRect(int x, int y, int w, int h);
}

DrawChar

The same as DrawTexture, but draws the texture of character code character from font. The output color may be modified by the font color cr.

DrawShape

TODO

DrawText

TODO

DrawTexture

Draws texture tex, possibly animated by the animation ticker if animate is true, at horizontal position x and vertical position y.

Various properties of this drawing process can be changed by passing extra arguments to this function. After all arguments are parsed, the "CleanMode" internal variable is used along with the specified virtual width/height to determine how to finally transform positions. CleanMode may be one of the following:

Name	Description
DTA_BASE	No position scaling is performed.
DTA_CLEAN	Scales all positions by Clean*Fac. See the documentation for those variables for more information.
DTA_CLEANNOMOVE	Scales the destination width and height by Clean*Fac.
DTA_CLEANNOMOVE_1	Scales the destination width and height by Clean*Fac_1.
DTA_FULLSCREEN	Sets the X and Y positions to 0. (Yes, really, this is all it does.)
DTA_HUDRULES	Scales all positions by the current status bar's scaling rules.
DTA_HUDRULESC	Scales all positions by the current status bar's scaling rules and centers the X position.

Here is a list of tags and their respective arguments which may be used:

Name	Arguments	Description
DTA_320X200	bool use	Sets CleanMode to DTA_BASE and the virtual width/height to 320/200 if use is true. Note that 320x200 does not scale properly to the screen as it must be 320x240 to do so.
DTA_ALPHACHANNEL	bool use	Does nothing unless DTA_FILLCOLOR is used and the render style is unspecified, in which case it will set the render style to "shaded" if use is true.
DTA_ALPHA	double alpha	Sets the alpha of the drawn texture to alpha.
DTA_BOTTOM320X200	bool use	Same as DTA_320X200, but also enables position transformation as if a call to VirtualToRealCoords with vbottom to true. Note that this is the only way to actually set this, but it may be overridden by following arguments to effectively toggle only this flag.
DTA_CENTERBOTTOMOFFSET	bool use	Same as DTA_CENTERBOTTOMOFFSET, but the Y offset is aligned to the bottom instead of the center.
DTA_CENTEROFFSET	bool use	Overrides the texture's X and Y offsets, centering them between the texture's height and width if use is true.
DTA_CLEANNOMOVE1	bool use	Sets CleanMode to DTA_CLEANNOMOVE1 if use is true.
DTA_CLEANNOMOVE	bool use	Sets CleanMode to DTA_CLEANNOMOVE if use is true.
DTA_CLEAN	bool use	Sets CleanMode to DTA_CLEAN if use is true.
DTA_CLIPBOTTOM, DTA_CLIPTOP	int length	Sets the vertical clipping for the texture.
DTA_CLIPLEFT, DTA_CLIPRIGHT	int length	Sets the horizontal clipping for the texture.
DTA_COLOROVERLAY	color cr	Multiplies cr with the texture. Alpha determines the intensity of this overlay. Applied before render styles.
DTA_COLOR	color cr	Multiplies cr with the texture. Applied after render styles change the color.
DTA_DESATURATE	int amount	Desaturates the texture by amount (range 0-255.)
DTA_DESTHEIGHTF, DTA_DESTWIDTHF	double size	Same as DTA_DESTHEIGHT/DTA_DESTWIDTH, but with decimal arguments.
DTA_DESTHEIGHT, DTA_DESTWIDTH	int size	Sets the resulting width or height on screen of the texture and sets CleanMode to DTA_BASE.
DTA_FILLCOLOR	color cr	Sets the render style to "stencil" if one is not specified and the fill color to cr.
DTA_FLIPX, DTA_FLIPY	bool use	Flips the X or Y position if use is true.
DTA_FULLSCREEN	bool use	Sets CleanMode to DTA_FULLSCREEN and the virtual width and height to the display size of the texture.
DTA_HUDRULES	int type	Sets CleanMode to DTA_HUDRULESC if type is BaseStatusBar.HUD_HORIZCENTER, or DTA_HUDRULES if it is BaseStatusBar.HUD_NORMAL.
DTA_KEEPRATIO	bool on	Enables aspect ratio correction if on is true.
DTA_LEFTOFFSETF, DTA_TOPOFFSETF	double ofs	Same as DTA_LEFTOFFSET/DTA_TOPOFFSETF, but with decimal arguments.
DTA_LEFTOFFSET, DTA_TOPOFFSET	int ofs	Overrides the texture's X or Y offset.
DTA_LEGACYRENDERSTYLE	int style	Overrides the render style. Note that there is also a DTA_RENDERSTYLE which cannot be used because the engine does not expose FRenderStyle yet.
DTA_MASKED	bool on	Turns the texture fully opaque (no alpha mask) if on is false. Default value is on.
DTA_SRCHEIGHT, DTA_SRCWIDTH	int size	Sets the width or height of the source image. Will cut the texture if lower than the original size. If the size is larger than the original, it will cause UV clamping, repeating the pixels at the image borders.
DTA_SRCX, DTA_SRCY	int pos	Sets the X or Y on the source image to start the texture at. Texture wrapping will cause a UV clamping effect, repeating the pixels at the image borders.
DTA_TRANSLATIONINDEX	int index	Remaps colors in the destination texture with translation table index.
DTA_VIRTUALHEIGHTF, DTA_VIRTUALWIDTHF	double size	Same as DTA_VIRTUALHEIGHT/DTA_VIRTUALWIDTH, but with decimal arguments.
DTA_VIRTUALHEIGHT, DTA_VIRTUALWIDTH	int size	Sets the virtual width or height to size.
DTA_WINDOWLEFTF, DTA_WINDOWRIGHTF	double size	Same as DTA_WINDOWLEFT/DTA_WINDOWRIGHT, but with decimal arguments.
DTA_WINDOWLEFT, DTA_WINDOWRIGHT	int size	Crops size pixels from the left or right.

Clear

Draws a rectangle from top left to bottom right in screen coordinates of cr color. Does not support translucent colors. palcolor is a palette index to use as a color in paletted renderers or -1 for automatic conversion from the given RGB color.

Dim

Draws a rectangle at x y of w h size in screen coordinates of cr color. Does not support translucent colors, but amount may be used to specify the translucency in a range of 0-1 inclusive.

DrawFrame

Draws a frame around a rectangle at x y of w h size in screen coordinates, using the border graphics as defined in MAPINFO/GameInfo.

DrawLine

Draws a one pixel wide line from x0 y0 to x1 y1 in screen coordinates of color cr with alpha alpha (range 0-255.)

DrawThickLine

Draws a thickness pixel wide line from x0 y0 to x1 y1 in screen coordinates of color cr with alpha alpha (range 0-255.)

GetAspectRatio

Returns the aspect ratio of the screen.

GetHeight

Returns the height of the screen.

GetWidth

Returns the width of the screen.

PaletteColor

Returns a color for a given palette index.

VirtualToRealCoords

Converts virtual coordinates pos from virtual coordinate space vsize to screen coordinate space size, possibly accounting for aspect ratio differences if handleaspect is true. If the ratio is 5:4, vbottom will account for the higher-than-wide conversion by repositioning vertically.

ClearClipRect

Clears the clipping rectangle if there is one.

GetClipRect

Returns the clipping rectangle's x/y/w/h.

GetViewWindow

Returns the 3D viewing window, which may be smaller than the screen size with any given screenblocks setting.

SetClipRect

Sets the clipping rectangle to restrict further drawing to the region starting at x y of size w h in screen coordinates.