VDI inquiry functions

inquiry functions More...

Functions
void	vq_cellarray (VdiHdl, short pxy[], short row_len, short nrows, short *el_used, short *rows_used, short *status, short color[])
short	vq_color (VdiHdl, short color_idx, short flag, short rgb[])
void	vq_extnd (VdiHdl, short flag, short work_out[])
void	vqf_attributes (VdiHdl, short atrib[])
void	vqin_mode (VdiHdl, short dev, short *mode)
void	vql_attributes (VdiHdl, short atrib[])
void	vqm_attributes (VdiHdl, short atrib[])
void	vqt_attributes (VdiHdl, short atrib[])
void	vqt_cachesize (VdiHdl, short which_cache, long *size)
void	vqt_extent (VdiHdl, const char *str, short extent[])
void	vqt_extent16 (VdiHdl, const short *wstr, short extent[])
void	vqt_extent16n (VdiHdl, const short *wstr, short num, short extent[])
void	vqt_fontinfo (VdiHdl, short *minade, short *maxade, short distances[], short *maxwidth, short effects[])
void	vqt_get_table (VdiHdl, short **map)
short	vqt_name (VdiHdl, short element, char *name)
short	vqt_width (VdiHdl, short chr, short *cw, short *ldelta, short *rdelta)
short	vq_gdos (void)
long	vq_vgdos (void)

Detailed Description

inquiry functions

todo: add description here

Function Documentation

void vq_cellarray	(	short	handle,
		short	pxy[],
		short	row_len,
		short	nrows,
		short *	el_used,
		short *	rows_used,
		short *	status,
		short	color[]
	)

returns the cell array definition of the specified pixels

Parameters

handle	Device handle
pxy
row_len	Length of each row in color index array.
nrows	Number of rows in color index array
el_used	Number of elements used in each row of color index array [option CHECK_NULLPTR] el_used may be NULL
rows_used	Number of rows used in color index array [option CHECK_NULLPTR] rows_used may be NULL
status	Invalid value flag: 0 if no errors 1 if a color value could not be determined for some pixel [option CHECK_NULLPTR] status may be NULL
color	Color index array, stored one row at time (-1) indicates that a color index could not be determined for that particular pixel

Since

all VDI versions

Color indices are returned one row at a time, starting from the top of the rectangular area, proceeding downward.

References VDI_CNTRLMAX.

short vq_color	(	short	handle,
		short	index,
		short	flag,
		short	rgb[]
	)

returns the RGB color intensity for a color index. You can either request the realized intensities or you can get the intensities you tried to set with vs_color().

Parameters

handle	Device handle
index	color index (pen)
flag	defined as follow: 0: return color values requested at vs_color() 1: return realized color values
rgb	intensity of red, green, blue

Returns

color index

Since

all VDI versions

@ note The color value you try to set via vs_color() can differ form the realized color value because a CLUT usually has less than 1000 levels per color component (e.g. 8 bit - 256 levels - per component). Most drivers for direct color devices return only the realized RGB value because the number of levels is sufficient.

References VDI_CNTRLMAX.

void vq_extnd	(	short	handle,
		short	flag,
		short	work_out[]
	)

This function either returns the output arguments of v_opnwk()/v_opnvwk() or additional device-specific information.

Parameters

handle	Device handle
flag	information type 0: return v_opnwk()/v_opnvwk() values 1: return additional information
work_out	work_out[0]: type of screen 0: no screen 1: separate alpha and graphic controllers and separate video memory 2: separate alpha and graphic controllers with shared video memory 3: common video an graphic controller with separate video memory 4: common alpha and graphic controller with shared video memory work_out[1]: number of color levels (refers to the CLUT) work_out[2]: supported text effects work_out[3]: raster scaling flag 0: scaling impossible 1: scaling possible work_out[4]: number of planes work_out[5]: CLUT flag 0: no CLUT 1: CLUT or pseudo-CLUT (true color) exists work_out[6]: performance factor work_out[7]: contour fill capability (v_contourfill) 0: not supported 1: contour fill supported work_out[8]: text rotation ability 0: none 1: in steps of 90 degree only 2: in steps of 1/10 degree work_out[9]: number of writing modes work_out[10]: available input levels 0: none 1: request 2: request and sample work_out[11]: text alignment flag 0: not available 1: available work_out[12]: inking capability flag 0: device cannot ink 1: device can ink work_out[13]: rubberbanding capability flag 0: no 1: capable of rubberband lines 2: capable of rubberband lines and rectangles work_out[14]: maximum number of input vertices or -1 (unlimited) work_out[15]: maximum number of intin arguments or -1 (no limit) work_out[16]: number of mouse keys work_out[17]: line types for wide lines 0: no 1: yes work_out[18]: number fo writing modes for wide lines work_out[19]: clipping flag 0: clipping off 1: clipping on work_out[20]: 0: extend precision pixel size information is not available 1: pixel size is in 1/10 microns 2: pixel size is in 1/100 microns 3: pixel size is in 1/1000 microns work_out[21]: pixel width in 1/10, 1/100 or 1/1000 microns work_out[22]: pixel height in 1/10, 1/100 or 1/1000 microns work_out[23]: horizontal resolution in dpi work_out[24]: vertical resolution in dpi work_out[28]: bezier flag (bit 1) 0: driver has not bezier capability 1: driver has bezier capability work_out[30]: raster flag (bit 0) 0: no scaling 1: vrt/vro_cpyfm() is capable of scaling bitmaps work_out[40]: not imprintable left border in pixels (printers/plotters) work_out[41]: not imprintable upper border in pixels (printers/plotters) work_out[42]: not imprintable right border in pixels (printers/plotters) work_out[43]: not imprintable lower border in pixels (printers/plotters) work_out[44]: page size (printers etc.), see v_opnwk()/vs_page_size() work_out[45..48]: clipping rectangle

Since

all VDI versions

Note:
If work_out[20] contains a nonzero value, work_out[21..24] and work_out[40..43] will contain extended information about pixel size and not imprintable borders. Usually margins only are returned for printer drivers due to mechanical limitations of the printer. Applications should take the margins into account to center the document correctly and they should display the margins on screen.

The addressable raster size returned by v_opnwk() (work_in[0/1]) is the area that can be imprinted. That means the upper left corner (0,0) of the imprintable page has a distance of (work_out[40], work_out[41]) pixels from the upper left corner of the physical sheet of paper.

If a driver returns more precise pixel sizes, this information should be used to calculate the position of graphic objects for printing. In worst case using the values from v_opnwk() in work_out[3/4] can result in a positioning inaccuracy of 2 or 3 mm (for output on a DIN A4 page).

The original ATARI VDI does not return the clipping flag (work_out[19]), but it returns the clipping rectangle.

You should not use the bezier flag (work_out[28]) to determine if the driver is capable of generating bezier curves because some drivers have bezier support but do not return the bezier flag. We recommend to use v_bez_on()!

References VDI_CNTRLMAX.

short vq_gdos

(

void

)

TODO

long vq_vgdos

(

void

)

TODO

void vqf_attributes	(	short	handle,
		short	attrib[]
	)

reports back the current attributes for filled objects.

Parameters

handle	Device handle
attrib	point to a 5-shorts array which will contain: attrib[0] fill type attrib[1] fill color attrib[2] fill style index attrib[3] writing mode attrib[4] perimeter flag

Since

all VDI versions

References VDI_CNTRLMAX.

void vqin_mode	(	short	handle,
		short	dev,
		short *	mode
	)

inquires the input mode of the specified device

Parameters

handle	Device handle
dev	input device (see vsin_mode())
mode	mode

Since

all VDI versions

References VDI_CNTRLMAX.

void vql_attributes	(	short	handle,
		short	attrib[]
	)

This function returns the current line attributes

Parameters

handle	Device handle
attrib	contain the following informations: attrib[0] line type attrib[1] line color attrib[2] writing mode attrib[3] line width attrib[4] end style for first point attrib[5] end style for last point

Since

all VDI versions

References VDI_CNTRLMAX.

void vqm_attributes	(	short	handle,
		short	attrib[]
	)

reports back the current marker attributes

Parameters

handle	Device handle
attrib	attrib[0] marker type attrib[1] marker color attrib[2] writing mode attrib[3] marker height attrib[4] marker width

Since

all VDI versions

References VDI_CNTRLMAX.

void vqt_attributes	(	short	handle,
		short	attrib[]
	)

This function returns the current graphic text attributes

Parameters

handle	Device handle
attrib	defined as follow: attrib[0] font id attrib[1] text color index attrib[2] text rotation in 1/10 of degrees attrib[3] horizontal alignment attrib[4] vertical alignment attrib[5] writing mode attrib[6] character width attrib[7] character height attrib[8] character cell width attrib[9] character cell height

Since

all VDI versions

Note

Some version of the ATARI-VDI return the writing mode - 1

References VDI_CNTRLMAX.

void vqt_cachesize	(	short	handle,
		short	which_cache,
		long *	size
	)

Parameters

handle	Device handle
which_cache
size

Since

References VDI_CNTRLMAX, VDI_INTOUTMAX, and VDI_PTSOUTMAX.

void vqt_extent	(	short	handle,
		const char *	str,
		short	extent[]
	)

If the selected font is a bitmap font, this function returns the minimal bounding box of a string. If the selected font is a vector font, the character widths (vqt_width()) will be added and the string (especially the leftmost and the rightmost character) might exceed the returned rectangle.

Parameters

handle	Device handle
str	string
extent	coordinates of the rectangle

Since

all VDI versions

The coordinates of the rectangle are given relative to a coordinate system, where the extent rectangle touches both, the x and y axes, and the string is in the first quadrant.

References VDI_CNTRLMAX, VDI_INTINMAX, and vdi_str2array_n().

void vqt_extent16	(	short	handle,
		const short *	wstr,
		short	extent[]
	)

see vqt_extent()

Parameters

handle	Device handle
wstr	string in 16-bit format (16 bits per character)
extent	coordinates of the rectangle

References VDI_CNTRLMAX, and vdi_wstrlen().

void vqt_extent16n	(	short	handle,
		const short *	wstr,
		short	num,
		short	extent[]
	)

see vqt_extent()

Parameters

handle	Device handle
wstr	string in 16-bit format (16 bits per character)
num	length of the string
extent	coordinates of the rectangle

References VDI_CNTRLMAX.

void vqt_fontinfo	(	short	handle,
		short *	minade,
		short *	maxade,
		short	distances[],
		short *	maxwidth,
		short	effects[]
	)

returns size information for the current font. Special effects and enlargment are taken into account.

Parameters

handle	Device handle
minade	minimum character index [option CHECK_NULLPTR] minade may be NULL
maxade	maximum character index [option CHECK_NULLPTR] maxade may be NULL
distances	distances[0]: distance of bottom line and baseline distances[1]: distance of descent line and baseline distances[2]: distance of half line and baseline distances[3]: distance of ascent line and basline distances[4]: distance of top line and baseline [option CHECK_NULLPTR] distances may be NULL
maxwidth	maximum character cell width [option CHECK_NULLPTR] maxwidth may be NULL
effects	effects[0]: additional character width due to text effects effects[1]: left offset of skewed text effects[2]: right offset of skewed text [option CHECK_NULLPTR] effects may be NULL

Since

all VDI versions

References VDI_CNTRLMAX.

void vqt_get_table	(	short	handle,
		short **	map
	)

Parameters

handle	Device handle
map

Since

References VDI_CNTRLMAX.

short vqt_name	(	short	handle,
		short	element,
		char *	name
	)

This function returns a 32-character string that describes the face.

Parameters

handle	Device handle
element
name

Returns

ID number

Since

all VDI versions; extended since NVDI 3.00 (add 33th byte to name for "bitmap/vector font" flag)

Note

if the name is 32 characters long, name is not 0 terminated !

some device driver returns -1 for their not available system font

References VDI_CNTRLMAX.

short vqt_width	(	short	handle,
		short	chr,
		short *	cw,
		short *	ldelta,
		short *	rdelta
	)

This call reports back the cell width for the specified character. If you have selected a vector font, the returned cell width is a rounded value. You can use this advance width for determing a character position when you use v_gtext() but you cannot use it for v_ftext() output.

Parameters

handle	Device handle
chr	character index
cw	character cell width [option CHECK_NULLPTR] cw may be NULL
ldelta	left character alignment delta [option CHECK_NULLPTR] ldelta may be NULL
rdelta	right character alignment delta [option CHECK_NULLPTR] rdelta may be NULL

Returns

character index or -1 (error)

Since

all VDI versions

Note:
To determine the width of a string, you should always call vqt_extent(), vqt_f_extent() or vqt_real_extent(). If you try to check whether a font is monospaced or proportional, you should test if vqt_name() returns extend information.

References VDI_CNTRLMAX.