graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPXVR - Set Extended View Representation

GPXVR (wsid, view, id, value)

Purpose

Use GPXVR to set one field in the entry of the specified workstation's view table.

The values specified are stored in the requested view table entry. When the application updates the workstation, the graPHIGS API sets the corresponding current values in the view table entry to the requested values. You can set only one field at a time with each subroutine call. Issue multiple invocations of GPXVR to set multiple fields.

The clipping indicators determine to which boundaries the contents of the view are clipped. The shielding indicator determines if the content of lower priority views may be displayed within the boundaries of the specified viewport. The border indicator specifies if a border is to be drawn around the viewport.

When set to 2=ON , the temporary view indicator indicates that the corresponding view will have its view activity changed frequently. Where possible the device support saves the current underlying screen image. This allows deactivation consist of restoring the underlying screen image without requiring structure traversal. A typical use of the temporary view capability is the "pop-up menu" found in many applications today.

Application developers should be aware of the following points:

The temporary view indicator acts as an indicator to the graPHIGS API that the corresponding view is active only for a short period of time. If used properly, it can greatly contribute to the interactive performance of viewport deactivation.

The best efficiency is gained when a temporary view is the highest priority active viewport.

When setting a view's projection type to perspective, any image mappings currently defined to the view are cancelled.

The view active flag for output determines if the view and its contents are displayed. The view active flag for input considers the view for transformation of locator and stroke input from Device Coordinate (DC) to World Coordinates (WC)

The antialiasing mode defines the algorithm that the graPHIGS API uses when rendering primitives within the specified view. It improves the quality of the image and reduces the jagged appearance of the objects. The highest quality image results when you set the antialiasing mode to 2=SUBPIXEL_ON_THE_FLY However, for better performance, set the antialiasing mode to 3=NON_SUBPIXEL_ON_THE_FLY Issuing the Set Antialiasing Mode (GPAID) structure element specifies whether the antialiasing algorithm is to be applied to the primitives within the view.

The shield alpha value defines the initial alpha value for the view shield. The value is used to initialize the destination alpha values when alpha planes are present and shielding indicator is on. The initial shield alpha value does not affect the initial shield color, but is used to blend subsequent primitives with the view shield when blending is in effect.

Other viewing parameters can also be controlled, such as Hidden Line/Hidden Surface Removal (HLHSR) mode, transparency processing, initial color processing, and initial frame buffer mask. Color processing mode and frame buffer protect mask are traversal defaults and are applied to images as well as to structure content.

The workstation's view table is 0 based, however, view entry 0 cannot be changed. (See The graPHIGS Programming Interface: Technical Reference for the default values for view entry 0)

Note:

The following functions are treated as other forms of this generic subroutine:
GPVCH - Set View Characteristics

GPXVCH - Set Extended View Characteristics

GPVMT2 - Set View Matrix 2

GPVMT3 - Set View Matrix 3

GPVMP2 - Set View Mapping 2

GPVMP3 - Set View Mapping 3

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

view -- specified by user, fullword integer

View table index (>=1)

id -- specified by user, fullword integer

Group identifier (1<= id<=24) See group identifier values defined below.

value -- specified by user, array of fullword quantities

The value to be set for each group is expressed in the following data formats:

Group Identifier 1 - Window clipping indicator

A fullword integer (1=NOCLIP, 2=CLIP )

Group Identifier 2 - Near clipping indicator

A fullword integer (1=NOCLIP, 2=CLIP )

Group Identifier 3 - Far clipping indicator

A fullword integer (1=NOCLIP, 2=CLIP )

Group Identifier 4 - Shielding indicator

A fullword integer (1=OFF, 2=ON )

Group Identifier 5 - Shielding color

Four fullwords of data with either of the following two formats:

      indexed format                        direct format
      -------------                         -------------
    0 |          1| fullword integer      0 |          2| fullword integer
      |-----------|                         |-----------|
    4 |color index| fullword integer      4 |component 1| short floating-point number
      |-----------|                         |-----------|
    8 |    ignored| fullword integer      8 |component 2| short floating-point number
      |-----------|                         |-----------|
   12 |    ignored| fullword integer     12 |component 3| short floating-point number
      -------------                         -------------

Group Identifier 6 - Border indicator

A fullword integer (1=OFF, 2=ON )

Group Identifier 7 - Border color

Four fullwords of data with either of the following two formats:

      indexed format                        direct format
      -------------                         -------------
    0 |          1| fullword integer      0 |          2| fullword integer
      |-----------|                         |-----------|
    4 |color index| fullword integer      4 |component 1| short floating-point number
      |-----------|                         |-----------|
    8 |    ignored| fullword integer      8 |component 2| short floating-point number
      |-----------|                         |-----------|
   12 |    ignored| fullword integer     12 |component 3| short floating-point number
      -------------                         -------------

Group Identifier 8 - Reserved

This field is reserved.

Group Identifer 9 - Temporary view indicator

A fullword integer (1=OFF, 2=ON )

Group Identifier 10 - HLHSR mode

A fullword integer (1=OFF, 2=ON_THE_FLY )

Group Identifier 11 - Transparency processing mode

A fullword integer (1=OFF, 2=PARTIAL_TRANSPARENT, 3=BLEND, 4=BLEND_ALL )

Group Identifier 12 - Initial color processing mode index

A fullword integer (>=0)

Note: This color processing index is not applied to shielding or border color.

Group Identifier 13 - Initial frame buffer write protect mask

A 32-bit bit string.

Note: The frame buffer mask is not applied to shielding or border color.

Group Identifier 14 - Viewport, 2D form

4 short floating-point numbers (including only Xmin, Xmax, Ymin, Ymax) For the set subroutine call, Zmin and Zmax are set to their default values.

Group Identifier 15 - Viewport, 3D form

6 short floating-point numbers (Xmin, Xmax, Ymin, Ymax, Zmin, Zmax)

Group Identifier 16 - View volume, 2D form

4 short floating-point numbers specifying the view window (Umin, Umax, Vmin, Vmax) For the set subroutine call, other fields of the view volume group are set to their default values.

Group Identifier 17 - View volume, 3D form

10 short floating-point numbers and a fullword integer specifying a view window (Umin,Umax,Vmin,Vmax), near plane distance, far plane distance, projection reference point (u, v, n), view plane distance and a projection type (1=PARALLEL, 2=PERSPECTIVE )

 
    -----------------------
    |        Umin         | short floating-point number
    |---------------------|
    |        Umax         | short floating-point number
    |---------------------|
    |        Vmin         | short floating-point number
    |---------------------|
    |        Vmax         | short floating-point number
    |---------------------|
    | near plane distance | short floating-point number
    |---------------------|
    |  far plane distance | short floating-point number (=>
near plane)
    |---------------------|
    |    U projection-    | short floating-point number
    |   reference point   |
    |---------------------|
    |    V projection-    | short floating-point number
    |   reference point   |
    |---------------------|
    |    N projection-    | short floating-point number
    |   reference point   |
    |---------------------|
    | view plane distance | short floating-point number
    |---------------------|
    |   projection type   | fullword integer
    -----------------------

Group Identifier 18 - View matrix, 2D form

9 short floating-point numbers. For the input view matrix, the elements are in the following order:

                 
    |m11  m12  m13|
    |m21  m22  m23|-->(m11,m12,m13,m21.....m33)
    |m31  m32  m33|

The 3[default]3 matrix is expanded by the graPHIGS API into a 4[default]4 matrix as follows:

                          
    |a  b  c|        |a b 0 c|
    |d  e  f| -----> |d e 0 f|
    |g  h  i|        |0 0 1 0|
                     |g h 0 i|

When inquired, the matrix returned is the expanded 4[default]4 matrix. For the set subroutine call, other elements are set to their default values.

Group Identifier 19 - View matrix, 3D form

16 short floating-point numbers. For the input view matrix, the elements must be in the following order:

                   
    | m11 m12 m13 m14 |
    | m21 m22 m23 m24 |---> (m11,m12,m13,m14,m21,m22,.....m44)
    | m31 m32 m33 m34 |
    | m41 m42 m43 m44 |

Group Identifier 20 - View input active flag

A fullword integer specifying the view that is to be made active/inactive for input (1=INACTIVE, 2=ACTIVE )

Group Identifier 21 - View output active flag

A fullword integer specifying the view that is to be made active/inactive for output (1=INACTIVE, 2=ACTIVE )

Group Identifier 22 - View mapping matrix, 2D form

9 short floating-point numbers including:

                 
    |m11  m12  m13|
    |m21  m22  m23| --->(m11,m12,m13,m21.....m33)
    |m31  m32  m33|

Group Identifier 23 - View mapping matrix, 3D form

16 short floating-point numbers including:

                    
     |m11 m12 m13 m14|
     |m21 m22 m23 m24| --->(m11,m12,m13,m14,m21,m22,.....m44)
     |m31 m32 m33 m34|
     |m41 m42 m43 m44|

Group Identifier 24 - Antialiasing mode

A fullword integer (1=OFF, 2=SUBPIXEL_ON_THE_FLY, 3=NON_SUBPIXEL_ON_THE_FLY )

Group Identifier 25 - Shield alpha value

A fullword integer (0<=alpha<=255 ) The default value of the shield alpha value is 255 (opaque).

Error Codes

25: SPECIFIED WORKSTATION DOES NOT EXIST
44: INVALID WINDOW DEFINITION
55: PRP IS POSITIONED ON THE VIEW PLANE
59: VIEW INDEX VALUE < ZERO
92: COLOR INDEX < ZERO
93: COLOR INDEX VALUE(S) EXCEED WORKSTATION TABLE CAPACITY
96: COLOR PARAMETER OUT OF RANGE FOR CURRENT COLOR MODEL
97: COLOR FORMAT PARAMETER IS INVALID
251: SPECIFIED HLHSR MODE IS NOT SUPPORTED
253: SPECIFIED ANTIALIASING MODE IS NOT SUPPORTED
260: SPECIFIED TRANSPARENT PROCESSING MODE IS NOT SUPPORTED
265: COLOR PROCESSING INDEX < ZERO
266: COLOR PROCESSING INDEX EXCEEDS THE WORKSTATION TABLE CAPACITY
272: GROUP IDENTIFIER IS INVALID
323: VIEW INDEX EXCEEDS VIEW TABLE CAPACITY
330: INVALID VIEWPORT
331: PROJECTION TYPE IS INVALID
332: CLIP INDICATOR VALUE IS INVALID
334: TEMPORARY VIEW INDICATOR IS INVALID
336: FAR CLIPPING PLANE IN FRONT OF NEAR CLIPPING PLANE
507: SHIELDING INDICATOR VALUE IS INVALID
508: VIEW ACTIVE FLAG VALUE IS INVALID
518: VIEW ZERO CANNOT BE MODIFIED
522: VIEW MATRIX IS SINGULAR
547: VIEW BORDER INDICATOR IS INVALID
639: SPECIFIED ALPHA VALUE IS INVALID

Related Subroutines

GPAID: Set Antialiasing Identifier
GPCML: Set Color Model
GPCPI: Set Color Processing Index
GPEVM2: Evaluate View Mapping Matrix 2
GPEVM3: Evaluate View Mapping Matrix 3
GPFBM: Set Frame Buffer Protect Mask
GPQAMO: Inquire Available Antialiasing Modes
GPQCVR: Inquire Current View Representation
GPQHMO: Inquire Available HLHSR Modes
GPQRVR: Inquire Requested View Representation
GPQTMO: Inquire Available Transparency Modes

RCP code

201330435 (X'0C000F03')