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.69  vq_color                                                   TOS

 Name:         »Inquire colour representation« - Obtain the RGB 
               intensities for a particular colour index.

 Opcode:       26

 Syntax:       void vq_color ( int16_t handle, int16_t color_index, 
               int16_t set_flag, int16_t *rgb );

 Description:  The call vq_color obtains the set RGB colour inten- 
               sities of the colour palette. The following apply:

                Parameter    Meaning

                handle       Workstation identifier
                color_index  Colour register index to be inquired
                set_flag     Flag for colour intensity:
                              0 =     Return colour values last 
                                      requested by user at vs_color
                              1 =     Return realized colour values
                rgb_in[0]    Red colour intensity (in tenths of a 
                             percent, 0-1000)
                rgb_in[1]    Green colour intensity (in tenths of a 
                             percent, 0-1000)
                rgb_in[2]    Blue colour intensity (in tenths of a 
                             percent, 0-1000)

               Notes: Set and actually realized colour intensities can 
               be different on systems using a CLUT if the number of 
               available colour steps is too small.

               Example: If a monitor only offers two intensities, then 
               its range divides into part-ranges 0..500 and 
               501..1000. The actual intensity can however only be 0 
               or 1000; no matter which number is selected from the 
               range from 501 to 1000, the intensity of 1000 will be 
               set every time; hence a set intensity can have the 
               value of 623, say, and the actual one the value 1000.

               With direct RGB (no CLUT), usually the actually set 
               intensity as well as the intensity passed by the user 
               will be returned, as the number of gradations is large 
               enough.

               Some colour printer drivers do not allow modifying the 
               colour of each register. There is a simple test for 
               checking if the driver permits you to change index 
               colours:

                  . Call vq_color with set_flag value of 0 and save 
                    the return
                  . Call vs_color to modify that colour index by a 
                    significant value
                  . Call vq_color with set_flag value of 0 and then 
                    compare it with what you set
                  . Restore old value
                  . If equivalent values are returned, you can modify 
                    each colour index

 Return value: The function returns -1 if the specified index is out 
               of range for the device; otherwise it does not return a 
               result.

 Availability: Supported by all drivers.

 Group:        Inquire functions

 See Also:     Binding   vs_color   vs_color2