Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File7.6.84  v_getbitmap_info                                           TOS

 Name:         »Get character bitmap information« - Obtain placement 
               information about the bitmap of a vector character.

 Opcode:       239

 Syntax:       void v_getbitmap_info ( int16_t handle, int16_t ch, 
               fix31 *advx, fix31 *advy, fix31 *xoff, fix31 *yoff, 
               int16_t *width, int16_t *height, int16_t **bitmap );

 Description:  The call v_getbitmap_info returns a pointer to the 
               character's bitmap and provides information about the 
               character placement, size and alignment.

                Parameter  Meaning

                handle     Workstation identifier
                ch         Character to return info about
                advx       X-advance in 1/65536 pixels
                advy       Y-advance in 1/65536 pixels
                xoff       X-offset in 1/65536 pixels
                yoff       Y-offset in 1/65536 pixels
                width      Bitmap width in pixels
                height     Bitmap height in pixels
                bitmap     Pointer to the bitmap

               Notes: advx/y represent the offset vectors for the 
               correct placement of the next character. x/yoff are 
               offset vectors of the top left corner of the bitmap 
               relative to the position of the character cell, and are 
               necessary because most bitmaps are smaller than the 
               character cell containing them.

               To get reproducible output even without NVDI, any text 
               effects should be switched off. As the pointer to the 
               bitmap points to the character cache as a rule, one 
               should copy the bitmap directly after the call (tip: 
               inhibit AES context switching with wind_update!) - 
               otherwise the pointer could be invalid already.

               Additionally one should not call v_getbitmap_info for 
               very large characters (e.g. 300 pts or more), as these, 
               depending on the cache size, may not be capable of 
               being built up completely; in this case the bitmap 
               contains only a part of the character.

               You should not use this function to write your own text 
               output function - this function would not be faster 
               than v_ftext and you would not be able to do pair 
               kerning. Use v_ftext!

 Return value: The function does not return a result.

 Availability: As of SpeedoGDOS 4.00 and as of NVDI 3.00. (The call 
               also existed in FSMGDOS but with a completely different 
               calling format; Atari changed it, as no FSMGDOS program 
               utilized it at the time.)

 Group:        Inquire functions

 See Also:     Binding   vst_effects   SpeedoGDOS   NVDI