{{fbdoc item="title" value="DRAW STRING"}}----
Graphics statement to render text to an image or screen.

{{fbdoc item="syntax"}}##
	**Draw String** [//buffer//,] [STEP] (//x//, //y//), //text// [,//color// [, //font// [, //method// [, (//alpha//|//blender//) [, //parameter//] ] ] ] ]
##
{{fbdoc item="usage"}}##
	**Draw String** [//buffer//,] [STEP] (//x//, //y//), //text// [, //color//]
	**Draw String** [//buffer//,] [STEP] (//x//, //y//), //text// , , //font// [, //method// [, //alpha// ] ]
	**Draw String** [//buffer//,] [STEP] (//x//, //y//), //text// , , //font//, [[KeyPgCustomgfx Custom]], //blender// [, //parameter//]
##
{{fbdoc item="param"}}
	##//buffer//##
		the sprite to draw the string on. If this is not supplied, it will be drawn to the screen.
	##STEP##
		use relative coordinates. If ##STEP## is added, the x and y coordinates are translated relative to the last drawn point.
	##//x//##, ##//y//##
		the horizontal / vertical position to draw to, relative to the top left hand corner of the screen (unless ##STEP## is used - see above).  The top left corner of the text will be drawn at this position.
	##//text//##
		the string containing the text to draw
	##//color//##
		if no font is supplied, this allows you to choose the color of the text.  If omitted, the default foreground ##[[KeyPgColor Color]]## is used.
		If a font is supplied, ##//color//## is ignored, and the font itself specifies the color for each pixel.
	##//font//##
		an image buffer containing a custom font. If no font is supplied, the standard font for the current text resolution is used, and the following parameters are ignored.
	##//method//## | ##**Custom**##
		specifies how the font characters are drawn on top of the target surface. The same methods as found for the ##[[KeyPgPutgraphics Put]]## statement are allowed, with the only difference that the default method is ##[[KeyPgTransGfx Trans]]## for this function.  This parameter only applies to custom fonts.
	##//alpha//##
		alpha value, ranging 0-255.  This parameter only applies to the ##[[KeyPgAddGfx Add]]## or ##[[KeyPgAlphaGfx Alpha]]## methods.
	##//blender//##
		custom blender function for the ##[[KeyPgCustomgfx Custom]]## drawing method; see ##[[KeyPgPutgraphics Put (Graphics)]]## statement description for details.  This parameter only applies to the ##[[KeyPgCustomgfx Custom]]## method.
	##//parameter//##
		optional ##[[KeyPgPointer pointer]]## to be passed to the custom blender function; if omitted, the default value is zero (##0##).

{{fbdoc item="desc"}}
	This graphics keyword prints a string to the screen with pixel positioning, transparent background, and can use an user-supplied font. **##Draw String##** does not update any text or graphics cursor.  It doesn't wrap at the end of line.  Tabs, carriage returns and other special characters have no special behavior in **##Draw String##**, and are treated as normal characters.
	
	In graphics mode, this function provides a flexible alternative to ##[[KeyPgPrint Print]]##.  It has several key advantages:
	    - ##**Draw String**## can print text to any coordinate on the screen, while ##[[KeyPgPrint Print]]## is constrained to the character grid accessible by ##[[KeyPgLocate Locate]]##.
	    - ##[[KeyPgPrint Print]]## will override the background behind the text with the current background color.  ##**Draw String**## does not do this: it leaves the pixels in the background untouched.
	    - Like ##[[KeyPgPutgraphics Put]]##, ##**Draw String**## has several different methods for printing text, such as ##[[KeyPgAlphaGfx Alpha]]## and ##[[KeyPgCustomgfx Custom]]##.
	    - ##**Draw String**## isn't limited to a single character set: it is possible to supply a custom font to be used instead.
	
	Note: If a custom font isn't supplied, **##Draw String##** will default to the standard font, as used by ##[[KeyPgPrint Print]]##, with character size dictated by ##[[KeyPgWidth Width]]##.  ##//method//## - if passed - will be ignored, and the text will be drawn using the color supplied, with a transparent background.

==The custom font format:==
	The font is stored in a standard ##[[KeyPgGetgraphics Get]]##/##[[KeyPgPutgraphics Put]]## buffer; the font has to be stored in a buffer using the same depth as the current color depth, otherwise **##Draw String##** will bump out with an illegal function call runtime error.

	The first line of pixels in the font buffer holds the header of the font, on a byte (**not** pixel) basis. The very first byte identifies the font header version; currently this must be ##0##. The second byte gives the ascii code of the first supported character in the font; the third byte gives the ascii code of the last supported character. So if the font supports the full range 0-255, ##0## and ##255## will be the contents of these two bytes.
	Next comes the width of each of the supported characters, each in a byte. Supposing the font holds 96 characters, ranging from 32 to 127 (inclusive), the header would have the first three bytes holding ##0##, ##32## and ##127##, followed by 96 bytes giving the widths of the corresponding chars.

	The font height is obtained by subtracting 1 from the buffer height, that is, while the first buffer line of pixels acts as a font header, the remaining lines define the glyphs' layout. The buffer must be as wide as necessary to hold all the supported character sprites in the same row, one after another.

{{fbdoc item="ex"}}
	This gives an example of basic ##**Draw String**## usage: it uses it to print ##"Hello world"## in the center of the screen:
{{fbdoc item="filename" value="examples/manual/gfx/drawstring.bas"}}%%(freebasic)
const w = 320, h = 200 '' screen dimensions

dim x as integer, y as integer, s as string

'' Open a graphics window
screenres w, h

'' Draw a string in the centre of the screen:

s = "Hello world"
x = (w - len(s) * 8) \ 2
y = (h - 1 * 8) \ 2

draw string (x, y), s

'' Wait for a keypress before ending the program
sleep
%%
{{image class="center" title="Draw String Example 1" url="/images/drawstr1.png"}}

	This example shows you how to create and use your own custom font.  For simplicity, it uses ##**Draw String**## with the default font to create the glyphs.
{{fbdoc item="filename" value="examples/manual/gfx/drawstring-custom.bas"}}%%(freebasic)
'' Define character range
const FIRSTCHAR = 32, LASTCHAR = 127

const NUMCHARS = (LASTCHAR - FIRSTCHAR) + 1
dim as ubyte ptr p, myFont
dim as integer i

'' Open a 256 color graphics screen (320*200)
screenres 320, 200, 8

'' Create custom font into PUT buffer

myFont = imagecreate(NUMCHARS * 8, 9)

 '' Put font header at start of pixel data

#ifndef ImageInfo '' older versions of FB don't have the ImageInfo feature
p = myFont + IIf(myFont[0] = 7, 32, 4)
#else
ImageInfo( myFont, , , , , p )
#endif

p[0] = 0
p[1] = FIRSTCHAR
p[2] = LASTCHAR

 '' PUT each character into the font and update width information
for i = FIRSTCHAR to LASTCHAR
	
	'' Here we could define a custom width for each letter, but for simplicity we use
	'' a fixed width of 8 since we are reusing the default font glyphs
	p[3 + i - FIRSTCHAR] = 8
	
	'' Create character onto custom font buffer by drawing using default font
	draw string myFont, ((i - FIRSTCHAR) * 8, 1), chr(i), 32 + (i mod 24) + 24
	
next i

'' Now the font buffer is ready; we could save it using BSAVE for later use
rem bsave "myfont.bmp", myFont

'' Here we draw a string using the custom font
draw string (10, 10), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", , myFont
draw string (10, 26), "abcdefghijklmnopqrstuvwxyz", , myFont
draw string (66, 58), "Hello world!", , myFont

'' Free the font from memory, now we are done with it
imagedestroy myFont

sleep
%%
{{image class="center" title="Draw String Example 2" url="/images/drawstr2.png"}}

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- ##[[KeyPgPrint (Print | ?)]]##
	- ##[[KeyPgDraw Draw]]##
	- ##[[KeyPgImagecreate ImageCreate]]##
	- ##[[KeyPgImageDestroy ImageDestroy]]##
	- ##[[KeyPgImageInfo ImageInfo]]##
	- ##[[KeyPgPutgraphics Put (Graphics)]]##
	- ##[[KeyPgWidth Width]]##

{{fbdoc item="back" value="CatPgGfx2D|2D Drawing Functions"}}