{{fbdoc item="title" value="CUSTOM"}}----
Parameter to the ##[[KeyPgPutgraphics|Put]]## graphics statement which selects a custom method

{{fbdoc item="syntax"}}##
	**Put** [ //target//, ] [ STEP ] ( //x//,//y// ), //source// [ ,( //x1//,//y1// )-( //x2//,//y2// ) ], **Custom**, //custom_function_ptr// [, //parameter//]
##
{{fbdoc item="param"}}
	##**Custom**##
		Required.
	##//custom_function_ptr//##
		name of the custom user defined function.
	##//parameter//##
		optional ##[[KeyPgPtr|pointer]]## to be passed to the custom function; if omitted, the default value is zero (##0##).

{{fbdoc item="desc"}}
	##**Custom**## selects a custom user defined function as the method for blitting an image buffer.
	
	The ##Custom## method uses a user-defined function to calculate the final pixel values to be drawn to the destination buffer. This function will be called once for every pixel of the source image, and will receive the source and destination pixel values, and a data pointer passed by the ##[[KeyPgPutgraphics|Put]]## function. The pixel value returned will be the value used to draw to the destination buffer. The function has the form:
	
	##[[KeyPgDeclare|declare]] [[KeyPgFunction|function]] //identifier// ( _
		[[KeyPgByval|byval]] //source_pixel// [[KeyPgAs|as]] [[KeyPgUlong|ulong]], _
		[[KeyPgByval|byval]] //destination_pixel// [[KeyPgAs|as]] [[KeyPgUlong|ulong]], _
		[[KeyPgByval|byval]] //parameter// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]] _
		) [[KeyPgAs|as]] [[KeyPgUlong|ulong]]##
		
	##//identifier//## is the name of the function.
	##//source_pixel//## is the current pixel value of the source image.
	##//destination_pixel//## is the current pixel value of the destination image.
	##//parameter//## is the parameter that is passed by the ##[[KeyPgPutgraphics|Put]]## command.  If it was omitted, its value will be zero.

{{fbdoc item="ex"}}
	{{fbdoc item="filename" value="examples/manual/gfx/custom.bas"}}%%(freebasic)
function dither ( byval source_pixel as ulong, byval destination_pixel as ulong, byval parameter as any ptr ) as ulong
	
	''either returns the source pixel or the destination pixel, depending on the outcome of rnd
	
	dim threshold as single = 0.5
	if parameter <> 0 then threshold = *cptr(single ptr, parameter)
	
	if rnd() < threshold then
		return source_pixel
	else
		return destination_pixel
	end if
	
end function


dim img as any ptr, threshold as single

'' set up a screen
screenres 320, 200, 16, 2
screenset 0, 1

'' create an image
img = imagecreate(32, 32)
line img, ( 0,  0)-(15,  15), rgb(255,   0,   0), bf
line img, (16,  0)-(31,  15), rgb(  0,   0, 255), bf
line img, ( 0, 16)-(15,  31), rgb(  0, 255,   0), bf
line img, (16, 16)-(31,  31), rgb(255,   0, 255), bf

'' dither the image with varying thresholds
do until len(inkey)
	
	cls
	
	threshold = 0.2
	put ( 80 - 16, 100 - 16), img, custom, @dither, @threshold
	
	'' default threshold = 0.5
	put (160 - 16, 100 - 16), img, custom, @dither
	
	threshold = 0.8
	put (240 - 16, 100 - 16), img, custom, @dither, @threshold
	
	screencopy
	sleep 25
	
loop

'' free the image memory
imagedestroy img
%%
{{image class="center" title="Put Custom example output" url="/images/custom.png"}}

{{fbdoc item="lang"}}
	- Not available in the //[[CompilerOptlang|-lang qb]]// dialect.

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

{{fbdoc item="see"}}
	- ##[[KeyPgPutgraphics|Put (Graphics)]]##

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