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

GPDMR - Set Data Mapping Representation

GPDMR (wsid, index, method, mdata, clengths, ctype, cdata)

Purpose

Use GPDMR to set the specified data mapping values into the specified entry of the data mapping table.

The data mapping representation provides the values that the graPHIGS API uses to perform data mapping on area primitives. The entry used is selected by the data mapping index specified by Set Data Mapping Index (GPDMI) or Set Back Data Mapping Index (GPBDMI) .

During traversal, if the data mapping method is inconsistent with the contents of the primitive, then the graPHIGS API renders the primitive using data mapping method 1=DM_METHOD_COLOR

If the method parameter has the value 1=DM_METHOD_COLOR , then you do not need to supply any additional data mapping data: the graPHIGS API ignores the values in the parameters following the method parameter.

The data mapping table is zero-based; however, entry zero cannot be changed. Entry zero always contains a data mapping method of 1=DM_METHOD_COLOR Use GPQWDT to inquire the data mapping facilities of a specific workstation.

See The graPHIGS Programming Interface: Understanding Concepts for more detailed information.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

index -- specified by user, fullword integer

Data mapping index (>=1).

method -- specified by user, fullword integer

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

mdata -- specified by user, variable data.

Data mapping method descriptor. This parameter must have one of the following formats, depending on the specified data mapping method:

-1=IMAGE_ARRAY

The following data is specified: 
                    ---------------------
     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 (>=1)

vdindex

Index into the primitive's data list for the v data value (>=1)

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 required: 
                    ---------------------
     WORDS 1        |      'dindex'     |  Fullword integer
                    |-------------------|
           2        |      'lolim'      |  Floatingpoint number
                    |-------------------|
           3        |      'hilim'      |  Floatingpoint number
                    ---------------------

dindex

Index into the primitive's data list (>=1)

lolim

Lower limit of the data mapping range

hilim

Upper limit of the data mapping range

4=BI_VALUE_UNIFORM

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

clengths -- specified by user, 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 required: 
                    ---------------------
     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 (>=1)

y_size

y dimension of the base color data array (>=1)

oformat

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

If data organization format selected is 2=SQUARE_MM or 3=RECT_MM , then x_size and y_size must be powers of 2.

1=DM_METHOD_COLOR

No data is required.

2=SINGLE_VALUE_UNIFORM

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

n_ent

The number of entries in the color data list (>=1)

4=BI_VALUE_UNIFORM

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

n_lists

The number of lists of data values (>=1)

n_ent

A list of fullword integers that specify the number of entries of each color data list (>=1). There are n_lists entries in this list.

ctype -- returned by the graPHIGS API, fullword integer

Data mapping color data type. Supported types are:

1=TYPE_COLOR

Colors consist of three short floating-point numbers in the current workstation color model (0<=color_component<=1). During traversal, the current transparency coefficient is used with these color values. See GPTCO for more information.

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. During traversal, the current transparency coefficient is used with these color values. See GPTCO for more information.

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). During traversal, these values override the current transparency coefficient. See GPTCO for more information.

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' [default] (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). During traversal, these values override the current transparency coefficient. See GPTCO for more information.

cdata -- specified by user, variable data

Data mapping color data. The data mapping color data organization is defined by the clengths and ctype parameters.

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 3 and Figure 4 The number of color values in each 2=SINGLE_VALUE_UNIFORM color list is given by n_ent

Figure 3. SINGLE_VALUE_UNIFORM Color Data Organization


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

The number of color values in each of the 4=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_ent[2] + n_ent[3] + ... + n_ent[n_lists])

Figure 4. BI-VALUE_UNIFORM Color Data Organization


       ^
       |            n_lists
vhilim + ------------------------------
       | | ^ | ^ |-^-| ^ |    | ^ | ^ |
       | |-|-| | |-|-| | |    | | | | |
       | | | |-|-|-|-| | |    |-|-| | |
       | | | | | |-|-| | |    | | | | |
V Data | |-|-| | |-|-| | |    | | | | |   n_ent[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 5 The number of color values in this array is

(x_size * y_size)

Figure 5. 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 6 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 6. IMAGE_ARRAY SQUARE_DATA 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 7 The number of color values in this complete array is

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

Figure 7. IMAGE_ARRAY RECT_DATA 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

3
FUNCTION REQUIRES STATE WSOP
25
SPECIFIED WORKSTATION DOES NOT EXIST
35
WORKSTATION HAS ONLY INPUT CAPABILITIES
50
WORKSTATION HAS ONLY INPUT CAPABILITIES
96
COLOR PARAMETER OUT OF RANGE FOR CURRENT COLOR MODEL
115
TRANSPARENT COEFFICIENT IS INVALID
275
SPECIFIED ENTRY CANNOT BE CHANGED
348
MINIMUM PARAMETER LIMIT > MAXIMUM
512
METHOD NOT SUPPORTED
630
DATA MAPPING INDEX < ZERO
634
DATA MAPPING COLOR TYPE NOT SUPPORTED
635
DATA ORGANIZATION FORMAT IS INVALID
637
DATA LIST INDEX IS INVALID
638
COLOR DATA LENGTHS PARAMETER IS INVALID

Related Subroutines

GPBDFM
Set Back Data Filtering Method
GPBDMI
Set Back Data Mapping Index
GPBDM2
Set Back Data Matrix 2
GPBTCO
Set Back Transparency Coefficient
GPDFM
Set Data Filtering Method
GPDMI
Set Data Mapping Index
GPDM2
Set Data Matrix 2
GPQDMR
Inquire Data Mapping Representation
GPTCO
Set Transparency Coefficient

RCP code

201345543 (X'0C004A07')

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