[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPQDMR - Inquire Data Mapping Representation

GPQDMR (wsid, index, lclengths, lcdata, errind, method, mdata, clengths, ctype, cdata)

Note:

This subroutine is a Workstation State List (WSL) inquiry. For an overview, see "WSL Inquiries"

Purpose

Use GPQDMR to inquire the current values in the specified entry of the workstation's data mapping table.

If the inquired information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the error indicator is 533 (an output parameter is not large enough to hold the requested data), then the values up to the length specified are returned. If the inquired information is unavailable, then the error indicator (errind) contains an error number indicating the reason, and the values returned in the output parameters are unpredictable.

If the method parameter has the value 1=DM_METHOD_COLOR , then the graPHIGS API returns no additional data in the remaining parameters.

The data mapping table is 0 based; entry 0 always contains a data mapping method of 1=DM_METHOD_COLOR

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

index -- specified by user, fullword integer

Data mapping index (>= 0).

lclengths -- specified by user, fullword integer

Length, in bytes, of the specified clengths parameter (>=0).

lcdata -- specified by user, fullword integer

Length, in bytes, of the specified cdata parameter (>=0).

errind -- returned by the graPHIGS API, fullword integer

Error indicator. If the error indicator is zero, the request has been completed. Otherwise, one of the following errors exists:
3
FUNCTION REQUIRES STATE WSOP
25
SPECIFIED WORKSTATION DOES NOT EXIST
35
WORKSTATION HAS ONLY INPUT CAPABILITIES
50
DATA MAPPING INDEX EXCEEDS WORKSTATION TABLE CAPACITY
509
DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH
533
INQUIRY DATA EXCEEDS AREA. OUTPUT TRUNCATED
630
DATA MAPPING INDEX < ZERO

method -- returned by the graPHIGS API, fullword integer

Data mapping method (-1=IMAGE_ARRAY, 1=DM_METHOD_COLOR, 2=SINGLE_VALUE_UNIFORM, 4=BI_VALUE_UNIFORM )

mdata -- returned by the graPHIGS API, variable data.

Data mapping method descriptor. The data returned in this parameter has one of the following formats, depending on the returned data mapping method (method):

-1=IMAGE_ARRAY

The following data is returned: 
                    ---------------------
     WORDS 1        |      'udindex'    |  Fullword integer
                    |-------------------|   
           2        |      'vdindex'    |  Fullword integer
                    |-------------------|
           3        |      'ulolim'     |  Floatingpoint number
                    |-------------------|
           4        |      'uhilim'     |  Floatingpoint number
                    |-------------------|
           5        |      'vlolim'     |  Floatingpoint number
                    |-------------------|
           6        |      'vhilim'     |  Floatingpoint number
                    ---------------------

udindex

Index into the primitive's data list for the u data value

vdindex

Index into the primitive's data list for the v data value

ulolim

Lower limit of the u data mapping range

uhilim

Upper limit of the u data mapping range

vlolim

Lower limit of the v data mapping range

vhilim

Upper limit of the v data mapping range

1=DM_METHOD_COLOR

N/A (No data mapping descriptor is returned for this method.)

2=SINGLE_VALUE_UNIFORM

The following data is returned: 
                    ---------------------
     WORDS 1        |      'dindex'     |  Fullword integer
                    |-------------------|
           2        |      'lolim'      |  Floatingpoint number
                    |-------------------|
           3        |      'hilim'      |  Floatingpoint number
                    ---------------------

dindex

Index into the primitive's data list

lolim

Lower limit of the data mapping range

hilim

Upper limit of the data mapping range

4=BI_VALUE_UNIFORM

The data mapping record returned is identical to -1=IMAGE_ARRAY

clengths -- returned by the graPHIGS API, variable data

Data mapping color data lengths. The format of this parameter is dependent on the method parameter:

-1=IMAGE_ARRAY

The following data is returned: 
                    ---------------------
     WORDS 1        |      'x_size'     |  Fullword integer
                    |-------------------|
           2        |      'y_size'     |  Fullword integer
                    |-------------------|
           3        |     'oformat'     |  Fullword integer
                    ---------------------

x_size

x dimension of the base color data array

y_size

y dimension of the base color data array

oformat

Data organization format (1=BASE_DATA, 2=SQUARE_MM, 3=RECT_MM ). This format determines the filtering methods which may be used.

1=DM_METHOD_COLOR

No data is returned

2=SINGLE_VALUE_UNIFORM

The following data is returned: 
                    ---------------------
     WORD  1        |      'n_ent'      |  Fullword Integer
                    ---------------------

n_ent

The number of entries in the color data list

4=BI_VALUE_UNIFORM

The following data is returned: 
                    ---------------------
     WORDS 1        |      'n_lists'    |  Fullword integer
                    |-------------------|
           2-n       |      'n_ent'      |   n_lists *
                    Z                   Z  Fullword integer
                    |                   |
                    ---------------------

n_lists

The number of lists of data values

n_ent

A list of fullword integers that specify the number of entries of each color data list. There are n_lists entries in this list.

ctype -- returned by the graPHIGS API, fullword integer

Data mapping color data type. Ignore this parameter if the method returned is 1=DM_METHOD_COLOR Returned types are:

1=TYPE_COLOR

Colors consist of three short floating-point numbers in the current workstation color model (0.0<=color_component<=1.0).

2=TYPE_PACKED_RGB

Colors consist of four bytes. The first three bytes represent the red, green, and blue color components respectively; the fourth byte is ignored.

3=TYPE_COLOR_TRANS

Colors consist of four short floating-point numbers. The first three numbers represent the color in the current workstation color model (0.0<=color_component<=1.0); the fourth number represents the transparency coefficient (0.0<=transparency_coefficient<=1.0).

4=TYPE_PACKED_RGB_ALPHA

Colors consist of four bytes. The first three bytes represent the red, green, and blue color components respectively; the fourth byte is an unsigned integer alpha ([default]) blending value that may be derived from a transparency coefficient as follows: 
Alpha=X'FF' x (1.0-transparency_coefficient)

(Alpha=X'00') is fully transparent and equivalent to (transparency_coefficient=1.0). (Alpha=X'FF') is fully opaque and equivalent to (transparency_coefficient=0.0).

cdata -- returned by the graPHIGS API, variable data

Data mapping color data. The data mapping color data organization is defined by the clengths and ctype parameters returned on this subroutine.

The 2=SINGLE_VALUE_UNIFORM and 4=BI_VALUE_UNIFORM color lists are supplied from the lolim lower limits to the hilim upper limits. For example, the color representing the data value lolim is first in each list, and the color representing hilim is last. See Figure 8 and Figure 9 The number of color values in each SINGLE_VALUE_UNIFORM color list is given by n_ent

Figure 8. SINGLE_VALUE_UNIFORM Color Data Organization


             n_ent
       ---------------
       | ----------> |
       ---------------
      -+-------------+-->
     lolim           hilim
         U Data Value

The number of color values in each of the BI_VALUE_UNIFORM color lists is specified by n_ent[i], so that the total number of color values in this color array is

(n_ent
1 + n_ent2, + n_ent3 + ... + n_entn_lists )

Figure 9. BI-VALUE_UNIFORM Color Data Organization


       
       |            n_lists
vhilim + --------------------------------  
       | | ^ | ^ |-^-| ^ |      | ^ | ^ |
       | |-|-| | |-|-| | |      | | | | |
       | | | |-|-|-|-| | |      |-|-| | |
       | |-|-| | |-|-| | |      | | | | |
V Data | | | | | |-|-| | |      | | | | | n_enti
i Value | |-|-|-|-|-|-|-|-| ---> |-|-|-|-| | | | | | |-|-| | | | | | | | | |-|-| | |-|-| | | | | | | | | | | |-|-|-|-| | | |-|-| | | | |-|-| | |-|-| | | | | | | | | | | | | |-|-| | | | | | | | vlolim + -------------------------------- -+------------------------------+--> ulolim uhilim U Data Value

The IMAGE_ARRAY color arrays are organized according to the oformat field of the clengths parameter. BASE_DATA array color data is supplied in row order left-to-right and bottom-to-top. See Figure 10 The number of color values in this array is

(x_size * y_size)

Figure 10. IMAGE_ARRAY BASE_DATA Color Data Organization


       ^
       |      x_size
vhilim + -----------------
       | |  -----------> |
       | |       ^       |
V Data | |       |       |
Value  | |       |       |  y_size
       | |               |
       | |  -----------> |
       | |  -----------> |
vlolim + -----------------
        -+---------------+--> 
       ulolim          uhilim
            U Data Value

SQUARE_MM color mipmap data is supplied in the same fashion, starting with the base image and continuing with each successively smaller mipmap image, until either x_size or y_size is equal to one. See Figure 11 The number of color values in this complete array is

(x_size * y_size) + (x_size * y_size)/4 + (x_size * y_size)/16 + ...
which reduces to the integer portion of 
((4 * x_size * y_size) - (MAX(x_size,y_size) / MIN(x_size,y_size))) / 3

Figure 11. IMAGE_ARRAY SQUARE_MM Color Data Organization


                                      ---
                                      | |
                                 --------
                                 |    |
                        x_size/2 |    |   (etc)
                         --------------
                         | ----> |
                         |  ^    |  y_size/2
       ^                 |  |    |
       |       x_size    | ----> |
vhilim + -------------------------
       | | ----------->  |
       | |       ^       |
V Data | |       |       |
 Value | |       |       |  y_size
       | |               |
       | | ----------->  |
       | | ----------->  |
vlolim + ----------------- 
         +---------------+---> 
       ulolim          uhilim
            U Data Value

RECT_MM color mipmap data is supplied as a complete set, and organized in row order left-to-right and bottom-to-top (as though the entire set of mipmap images constituted a single base texture image). See Figure 12 The number of color values in this complete array is

((2 * x_size) - 1) * ((2 * y_size) - 1)

Figure 12. IMAGE_ARRAY RECT_MM Color Data Organization


              x_size     x_size/2  (etc)
         -------------------------------
         |--------------|---------|---|-|
         |           ^  |         |   | |  (etc)
         |-----------|--|---------|---|-|
       ^ |           |  |         |   | |
       | |              |         |   | |  y_size/2
       | | -------------|---------|---> |
vhilim + |--------------|---------|---|-| 
       | | -------------|---------|---> |
       | |           ^  |         |   | |
V Data | |           |  |         |   | |
 Value | |           |  |         |   | |  y_size
       | |              |         |   | |
       | | -------------|---------|---> |
       | | -------------|---------|---> |
vlolim + -------------------------------- 
       | +--------------+---> 
       ulolim          uhilim
            U Data Value

Error Codes

None

Related Subroutines

GPBDMI
Set Back Data Mapping Index
GPBTCO
Set Back Transparency Coefficient
GPDMI
Set Data Mapping Index
GPDMR
Set Data Mapping Representation
GPTCO
Set Transparency Coefficient

RCP code

201339159 (X'0C003117')

[ Previous | Next | Contents | Glossary | Home | Search ]