doc/autodoc/displayhandler.doc
Contents
0_ABOUT
1_INDEX
2_STRUCTURES
Function reference
TDisAllocBitmap
TDisAllocPen
TDisBegin
TDisBlit
TDisBox
TDisBoxf
TDisCreateView
TDisDescribe
TDisEllipse
TDisEllipsef
TDisEnd
TDisFill
TDisFindDisplay
TDisFlush
TDisGetBestMode
TDisGetDisplayCaps
TDisGetDisplayProperties
TDisGetModeList
TDisGetMsg
TDisLine
TDisLock
TDisMovePixels
TDisPlot
TDisPoly
TDisPolyf
TDisPutImage
TDisSetAttrs
TDisSetBPen
TDisSetDPen
TDisSetPalette
TDisSimpleCreateView
TDisTextout
TDisUnlock
TDisWaitMsg
SHORT
API documentation for the displayhandler module.
the displayhandler module manages the creation, handling and drawing
inside of windows and screens with the various display modules depending
on the underlaying host operating system.
VERSION
$Id: displayhandler.html,v 1.2 2004/01/03 18:20:17 dtrompetter Exp $
REVISION HISTORY
$Log:
FUNCTIONS
TDisFindDisplay
TDisGetDisplayProperties
TDisGetModeList
TDisGetBestMode
TDisCreateView
TDisSimpleCreateView
TDisGetDisplayCaps
TDisWaitMsg
TDisGetMsg
TDisSetAttrs
TDisFlush
TDisAllocPen
TDisSetDPen
TDisSetBPen
TDisSetPalette
TDisAllocBitmap
TDisDescribe
TDisLock
TDisUnlock
TDisBegin
TDisEnd
TDisBlit
TDisTextout
TDisPutImage
TDisFill
TDisPlot
TDisLine
TDisBox
TDisBoxf
TDisPoly
TDisPolyf
TDisEllipse
TDisEllipsef
TDisMovePixels
TDISRECT()
TDISPROPS()
TDISCAPS()
TDISDESCRIPTOR()
TDISKEY()
TDISMOUSEPOS()
TDISMBUTTON()
TDISMSG()
TDISMODE()
NAME
TDisFindDisplay - find a display host according to the given tags
SYNOPSIS
display = TDisFindDisplay(dhandler, tags)
THNDL* TAPTR TTAGITEM*
FUNCTION
according to the given tags, this functions returns the handle of the
best matching display host module.
INPUT TAGS
TDISMUSTHAVE_CLASS, (TINT)
TDISMUSTNOTHAVE_CLASS, (TINT)
the class the display has to be or not
available tyes: TDISCLASS_STANDARD
TDISCLASS_OPENGL
TDISMUSTHAVE_MODE, (TINT)
TDISMUSTNOTHAVE_MODE, (TINT)
the mode the display has to support or not
available tyes: TDISMODE_WINDOW
TDISMODE_FULLSCREEN
TDISMUSTHAVE_COLORS, (TINT)
TDISMUSTNOTHAVE_COLORS, (TINT)
colordepth the display has to support or not
available tyes: TDISCOLORS_CLUT
TDISCOLORS_TRUECOLOR
TDIS_MINWIDTH, (TINT)
TDIS_MINHEIGHT, (TINT)
minimum width and height the display has to support
RESULTS
display - a handle of a display host module or TNULL
NOTES
to close a display call TDestroy from exec
SEE ALSO
TDisGetDisplayCaps, TDisGetModeList, TDisGetBestMode,
TDisCreateView
NAME
TDisGetDisplayProperties - get properties of a display host module
SYNOPSIS
TDisGetDisplayProperties(dhandler, display, props)
TAPTR THNDL* TDISPROPS()*
FUNCTION
fills a TDISPROPS() struct with the properties of the given display host
INPUTS
display - handle to display host
RESULTS
props - the properties of the display host will be available in the
TDISPROPS() structure
NOTES
before a application creates a view, this can be called to determine,
if this display module has the properties needed by the application.
SEE ALSO
TDisGetDisplayCaps, TDisGetModeList, TDisGetBestMode,
TDisCreateView
NAME
TDisGetModeList - fills a list with available displaymodes
SYNOPSIS
nummodes=TDisGetModeList(dhandler, display, modelist)
TINT TAPTR THNDL* TDISMODE()**
FUNCTION
fills a list with all available display modes, and return the number
of available modes.
INPUTS
display - handle to display host
RESULTS
modelist - points to a field of TDISMODE() structures
nummodes - number of available modes
NOTES
only of use for fullscreen display, windowed displays will return zero
SEE ALSO
TDisGetDisplayProperties, TDisGetDisplayCaps, TDisGetBestMode,
TDisCreateView
NAME
TDisGetBestMode - gets best displaymode
SYNOPSIS
mode=TDisGetBestMode(dhandler, display, w, h, d)
TDISMODE()* TAPTR THNDL* TINT TINT TINT
FUNCTION
seek and return the best displaymode for the chosen display host
according to the given parameters
INPUTS
display - handle to display host
w - desired width
h - desired height
d - desired color depth
RESULTS
a pointer to a valid TDISMODE() struct, or TNULL if no matching mode was
found
SEE ALSO
TDisGetDisplayProperties, TDisGetDisplayCaps, TDisGetModeList,
TDisCreateView
NAME
TDisCreateView - creates a view according to the given tags
SYNOPSIS
res = TDisCreateView(dhandler, display, tags)
TBOOL TAPTR THNDL* TTAGITEM*
FUNCTION
this creates a view with the chosen display host module according to the
given tags
INPUTS
display - handle to display host
INPUT TAGS
TDISC_WIDTH - desired width
TDISC_HEIGHT - desired height
TDISC_DEPTH - desired color depth
TDISC_TITLE - window title string
TDISC_XPOS - desired x-position of the window
TDISC_YPOS - desired y-position of the window
TDISC_FLAGS - custom flags
FLAGS
TDISCF_DOUBLEBUFFER - display should be double buffered
TDISCF_RESIZEABLE - window should be resizeable
RESULTS
res - TTRUE, if a screen/window could be created, else TFALSE
SEE ALSO
TDisGetDisplayProperties, TDisGetDisplayCaps, TDisGetModeList,
TDisGetBestMode
NAME
TDisSimpleCreateView - creates a view on the easy way
SYNOPSIS
display = TDisSimpleCreateView(dhandler, title, w, h, d,
opengl, fullscreen, dblbuf, resize)
THNDL* TAPTR TSTRPTR TINT TINT TINT
TBOOL TBOOL TBOOL TBOOL
FUNCTION
simplifies the creation of a windows/screen to one single call. this
uses the functions above and should cover the most needed features for
a display.
INPUTS
title - title for application
w - desired width
h - desired height
d - desired color depth
opengl - TTRUE, if the display must support OpenGL
fullscreen - TTRUE, if the display should be fullscreen
dblbuf - TTRUE for doublebuffering
resize - TTRUE, if a window has to be resizable
RESULTS
display - a THNDL* to a valid display or TNULL
NOTES
opengl is a MUSTBE - condition. doublebuffering is always supported
by the display host modules, same for resize. if no fullscreen
is available, the displayhandler tries to create a windowed display.
The values for width, height and depth HAVE to be checked with
dis_describe() after the view was created, they can differ from the
wished values!
to close a display call TDestroy from exec
SEE ALSO
TDisDescribe, TDisGetDisplayCaps
NAME
TDisGetDisplayCaps - get capabilities of a display host module
SYNOPSIS
TDisGetDisplayCaps(dhandler, display, caps)
TAPTR THNDL* TDISCAPS()*
FUNCTION
fills a TDISCAPS() struct with the capabilities of the given display
host
INPUTS
display - handle to display host
RESULTS
caps - the capabilities of the display host will be available in the
TDISCAPS() structure
NOTES
in contrast to TDisGetDisplayProperties, this should be called AFTER
a view was created.
SEE ALSO
TDisGetDisplayProperties, TDisGetModeList, TDisGetBestMode,
TDisCreateView, TDisSimpleCreateView
NAME
TDisWaitMsg - waits for a message
SYNOPSIS
TDisWaitMsg(dhandler, display)
TAPTR THNDL*
FUNCTION
waits for a message from the chosen display
INPUTS
display - handle to display host
RESULTS
SEE ALSO
TDisGetMsg
NAME
TDisGetMsg - returns a message, if theres any
SYNOPSIS
msg = TDisGetMsg(dhandler, display)
TDISMSG()* TAPTR THNDL*
FUNCTION
get a message from the chosen display and remove the message from the
messagequeue.
msg->code can be one of the following:
TDISMSG_CLOSE - user has pressed the close button of a window
TDISMSG_RESIZE - window has changed his size, msg->data points
to a TDISRECT() structure
TDISMSG_REDRAW - content of window has to redrawn
TDISMSG_ACTIVATED - application was activated
TDISMSG_DEACTIVATED - application was deactivated
TDISMSG_ICONIC - application is iconified (no redraw!)
TDISMSG_MOVE - windows was moved, msg->data points to a
TDISRECT() structure
TDISMSG_KEYDOWN - a key was pressed, msg->data points to a
TDISKEY() structure
TDISMSG_KEYUP - a key was released, msg->data points to a
TDISKEY() structure
TDISMSG_MOUSEMOVE - the mouse was moved, msg->data points to a
TDISMOUSEPOS() structure
TDISMSG_MBUTTONDOWN - a mousebutton was pressed, msg->data points to
a TDISMBUTTON() structure
TDISMSG_MBUTTONUP - a mousebutton was released, msg->data points
to a TDISMBUTTON() structure
TDISMSG_MWHEELDOWN - the mousewheel was scrolled down
TDISMSG_MWHEELUP - the mousewheel was scrolled up
(the following are not implemented yet)
TDISMSG_MWHEELLEFT - the mousewheel was scrolled left
TDISMSG_MWHEELRIGHT - the mousewheel was scrolled up
INPUTS
display - handle to display host
RESULTS
a pointer to a TDISMSG() structure, or TNULL, if there were no pending
messages
SEE ALSO
TDisWaitMsg
NAME
TDisSetAttrs - allows the change of some display attributes at runtime
SYNOPSIS
TDisGetMsg(dhandler, display, tags)
TAPTR THNDL* TTAGITEM*
FUNCTION
controls the behavior of some display properties
INPUTS
display - handle to display host
INPUT TAGS
TDISTAG_POINTERMODE - can be TDISPTR_NORMAL for the host typical
standard mouse pointer, TDISPTR_BUSY for the
host typical busy mouse pointer, or
TDISPTR_INVISIBLE to make the pointer invisible
TDISTAG_DELTAMOUSE - TTRUE to get delta mickeys instead of absolute
mouse coordinates
TDISTAG_VSYNCHINT - if supported, a TTRUE forces TDisFlush to be
synced to the display refresh to avoid teasing
effects
TDISTAG_SMOOTHHINT - if supported, a TTRUE forces bilinear
interpolation for scaled blits
RESULTS
NOTES
please remark, that any attribute whose name ends up with "HINT" is a
possiblity, not a necessity
SEE ALSO
NAME
TDisFlush - makes the display content visible
SYNOPSIS
TDisFlush(dhandler, display)
TAPTR THNDL*
FUNCTION
flushes the chosen display. this one is ABSOLUTELY required to make
display contents visible!
exchanges also front/backbuffer for doublebuffered displays.
INPUTS
display - handle to display host
RESULTS
NOTES
on some hosts is vertical sync available via TDisSetAttrs
SEE ALSO
TDisSetAttrs
NAME
TDisAllocPen - allocate a pen
SYNOPSIS
pen = TDisAllocPen(dhandler, display, color)
THNDL* TAPTR THNDL* TUINT
FUNCTION
allocates a pen for drawing on the chosen display
INPUTS
display - handle to display host
color - a integer containing a RGB value
RESULTS
handle to pen, or TNULL
NOTES
to release a allocated pen call TDestroy from exec
SEE ALSO
TDisSetDPen
NAME
TDisSetDPen - set the drawing pen
SYNOPSIS
TDisSetDPen(dhandler, display, pen)
TAPTR THNDL* THNDL*
FUNCTION
set the pen for drawing functions
INPUTS
display - handle to display host
pen - handle to pen
RESULTS
SEE ALSO
TDisAllocPen
NAME
TDisSetPalette - set the palette for 8bit displays
SYNOPSIS
TDisSetPalette(dhandler, display, palette, sp, sd, numentries)
TAPTR THDNL* TIMGARGBCOLOR()* TINT TINT TINT
FUNCTION
set the color lookup table for a 8bit display
INPUTS
display - handle to display host
palette - pointer to a TIMGARGBCOLOR() structure containing the
palette
sp - start color inside the palette
sd - start color inside the display palette
numentries - number of palette entries to set
RESULTS
NOTES
does nothing for hi- or truecolor displays
SEE ALSO
NAME
TDisAllocBitmap - allocates a bitmap
SYNOPSIS
bm = TDisAllocBitmap(dhandler, display, w, h, flags)
THNDL* TAPTR THNDL* TINT TINT TINT
FUNCTION
allocates a bitmap from a display. the color depth and color
format of the bitmap will be the same like the display.
INPUTS
display - handle to display host
w - width
h - height
flags - some of the following:
TDISCF_SCALEBLIT - scaling is needed for blitting
TDISCF_CKEYBLIT - color keying is needed for blitting
TDISCF_CALPHABLIT - alpha blending is needed for blitting
RESULTS
bm - a handle to a allocated bitmap or TNULL
NOTES
displayhandler returns zero, if a host isn't able to handle the wished
bitmap flags.
to release a allocated bitmap call TDestroy from exec
SEE ALSO
TDisBlit
NAME
TDisDescribe - get the image properties of a display or bitmap
SYNOPSIS
TDisDescribe(dhandler, handle, desc)
TAPTR THNDL* TDISDESCRIPTOR()*
FUNCTION
fills the given TDISDESCRIPTOR() - structure with the properties of
the chosen display or bitmap
INPUTS
handle - handle to a display or bitmap
RESULTS
desc - TDISDESCRIPTOR() structure with the properties of the display
or bitmap
NOTES
SEE ALSO
NAME
TDisLock - locks a display or bitmap
SYNOPSIS
res = TDisLock(dhandler, handle, img)
TBOOL TAPTR THNDL* TIMGPICTURE*
FUNCTION
locks a display or the chosen bitmap and grants direct access to the
pixel data buffer.
INPUTS
handle - handle to a display or bitmap
RESULTS
img - TIMGPICTURE structure with the properties of the display
or bitmap, and a valid data pointer to access to
res - TTRUE, if successfull locked, else TFALSE
NOTES
NEVER forget to do TDisUnlock! No rendering calls (text,line,plot and
so one) are allowed inside a lock! A lock has to be as short as
possible, because on most hosts it will stall the multitasking!
NOT allowed inside a TDisBegin/TDisEnd() area!!!
for TIMGPICTURE look into the documentation of imgproc
SEE ALSO
TDisUnlock
NAME
TDisUnlock - unlocks a locked display or bitmap
SYNOPSIS
TDisUnlock(dhandler, handle)
TAPTR THNDL*
FUNCTION
unlocks a locked display or bitmap, makes rendering calls possible again
INPUTS
handle - handle to a display or bitmap
RESULTS
NOTES
SEE ALSO
TDisLock
NAME
TDisBegin - allows use of rendering functions
SYNOPSIS
res = TDisBegin(dhandler, handle)
TBOOL TAPTR THNDL*
FUNCTION
Allowes rendering inside the chosen display or bitmap with following
functions: TDisTextOut(), TDisFill, TDisPlot, TDisLine, TDisBox,
TDisBoxf, TDisPoly, TDisPolyf, TDisEllipse, TDisEllipsef,
TDisMovePixels.
This has NOT to be called for TDisBlit and TDisFlush!
INPUTS
handle - handle to a display or bitmap
RESULTS
res - TTRUE, if rendering can start after this, else TFALSE
NOTES
NEVER forget to do TDisEnd!!! NOT allowed inside a
TDisLock/TDisUnlock() area!!!
SEE ALSO
TDisEnd
NAME
TDisEnd - finish usage of rendering functions
SYNOPSIS
TDisEnd(dhandler)
TAPTR
FUNCTION
Stop and finish for rendering functions.
INPUTS
RESULTS
SEE ALSO
TDisBegin
NAME
TDisBlit - blits a bitmap to their display
SYNOPSIS
res = TDisBlit(dhandler, bmhndl, tags)
TAPTR THNDL* TTAGITEM*
FUNCTION
blits a bitmap to their parent display, according to the given tags
INPUTS
bmhndl - handle to bitmap
tags - taglist
INPUT TAGS
TDISB_SRCX - x start in bitmap
TDISB_SRCY - y start in bitmap
TDISB_SRCWIDTH - width of area to blit
TDISB_SRCHEIGHT - height of area to blit
TDISB_DSTX - x destination in display
TDISB_DSTY - y destination in display
TDISB_DSTWIDTH - width of blitted area in display
TDISB_DSTHEIGHT - height of blitted area in display
TDISB_CKEY - color key value for color key blits
TDISB_CALPHA - alpha blending value for blitting with constant alpha
RESULTS
res - TTRUE, if blit occured, else TFALSE
SEE ALSO
NAME
TDisTextout - draws some text
SYNOPSIS
TDisTextout(dhandler, text, row, column)
TAPTR TSTRPTR TINT TINT
FUNCTION
renders text at the given position into a display or bitmap
INPUTS
text - string pointer to text
row - row for first char
column - column for first char
RESULTS
NOTES
uses the default font from the display host.
SEE ALSO
NAME
TDisPutImage - transfers a offscreenimage to a display or bitmap
SYNOPSIS
TDisPutImage(dhandler, handle, img, tags)
TAPTR THNDL* TIMGPICTURE* TTAGITEM*
FUNCTION
draws a offscreen image to the chosen display or bitmap, does
converting or scaling, if needed
INPUTS
handle - handle to a display or bitmap
img - TIMGPICTURE structure describing the offscreen image
tags - taglist
INPUT TAGS
TDISB_SRCX - x start in image
TDISB_SRCY - y start in image
TDISB_SRCWIDTH - width of area to transfer
TDISB_SRCHEIGHT - height of area to transfer
TDISB_DSTX - x destination in display or bitmap
TDISB_DSTY - y destination in display or bitmap
TDISB_DSTWIDTH - width of blitted area in display or bitmap
TDISB_DSTHEIGHT - height of blitted area in display or bitmap
RESULTS
NOTES
for TIMGPICTURE look into the documentation of imgproc
SEE ALSO
NAME
TDisFill - color fills display or bitmap
SYNOPSIS
TDisFill(dhandler)
TAPTR
FUNCTION
fill display or bitmap with actual drawpen
INPUTS
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisPlot - draws a pixel
SYNOPSIS
TDisPlot(dhandler, x, y)
TAPTR TINT TINT
FUNCTION
sets a pixel at given position into display or bitmap
INPUTS
x - x position of pixel
y - y position of pixel
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisLine - draws a line
SYNOPSIS
TDisLine(dhandler, sx, sy, ex, ey)
TAPTR TINT TINT TINT TINT
FUNCTION
draws a line into display or bitmap
INPUTS
sx - start x position of line
sy - start y position of line
ex - end x position of line
ey - end y position of line
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisBox - draws a box
SYNOPSIS
TDisBox(dhandler, sx, sy, w, h)
TAPTR TINT TINT TINT TINT
FUNCTION
draws a box into display or bitmap
INPUTS
sx - start x position of line
sy - start y position of line
w - width of box
h - height of box
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisBoxf - draws a filled box
SYNOPSIS
TDisBoxf(dhandler, sx, sy, w, h)
TAPTR TINT TINT TINT TINT
FUNCTION
draws a filled box into display or bitmap
INPUTS
sx - start x position of line
sy - start y position of line
w - width of box
h - height of box
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisPoly - draws a polygon
SYNOPSIS
TDisPoly(dhandler, numpoints, points)
TAPTR TINT TINT*
FUNCTION
draws a polygon into display or bitmap
INPUTS
numpoints - number of points
points - a field describing the polygon points, containing a
sequence of x and y coordinates
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisPolyf - draws a filled polygon
SYNOPSIS
TDisPolyf(dhandler, numpoints, points)
TAPTR TINT TINT*
FUNCTION
draws a filled polygon into display or bitmap
INPUTS
numpoints - number of points
points - a field describing the polygon points, containing a
sequence of x and y coordinates
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisEllipse - draws a ellipse
SYNOPSIS
TDisEllipse(dhandler, x, y, rx, ry)
TAPTR TINT TINT TINT TINT
FUNCTION
draws a ellipse into display or bitmap
INPUTS
x - x position of center of the ellipse
y - y position of center of the ellipse
rx - x radius of the ellipse
ry - y radius of the ellipse
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisEllipsef - draws a filled ellipse
SYNOPSIS
TDisEllipsef(dhandler, x, y, rx, ry)
TAPTR TINT TINT TINT TINT
FUNCTION
draws a filled ellipse into display or bitmap
INPUTS
x - x position of center of the ellipse
y - y position of center of the ellipse
rx - x radius of the ellipse
ry - y radius of the ellipse
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
NAME
TDisMovePixels - draws a filled ellipse
SYNOPSIS
TDisMovePixels(dhandler, sx, sy, dx, dy, w, h)
TAPTR TINT TINT TINT TINT TINT TINT
FUNCTION
moves a rectangle inside a bitmap or display to another position
INPUTS
sx - x position of rectangle
sy - y position of rectangle
dx - destination x position of rectangle
dy - destination x position of rectangle
w - width of rectangle
h - height of rectangle
RESULTS
SEE ALSO
TDisAllocPen, TDisSetDPen, TDisBegin
Rendered with docco TEKlib document generator