Vertex Structures

QuickDraw 3D RAVE / QuickDraw 3D RAVE Reference

Vertex Structures
QuickDraw 3D RAVE supports two different types of vertices: Gouraud vertices and texture vertices. You use Gouraud vertices for drawing Gouraud-shaded triangles, and also for drawing points and lines. A Gouraud vertex is defined by the TQAVGouraud data structure, which specifies the position, depth, color, and transparency information.
typedef struct TQAVGouraud {
   float                      x;
   float                      y;
   float                      z;
   float                      invW;
   float                      r;
   float                      g;
   float                      b;
   float                      a;
} TQAVGouraud;
Field Description

x
The x coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
y
The y coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
z
The depth of the vertex. The value of this field is a floating-point number between 0.0 and 1.0 inclusive, where lower numbers specify points closer to the origin.
invW
The inverse w value (that is, the value 1/w, where w is the homogeneous correction factor). This field is valid only for drawing engines that support the kQAOptional_PerspectiveZ feature. When the state variable kQATag_PerspectiveZ is set to kQAPerspectiveZ_On, hidden surface removal is performed using the value in this field rather than the value in the z field, thereby causing the hidden surface removal to be perspective corrected.
r
The red component of the vertex color.
g
The green component of the vertex color.
b
The blue component of the vertex color.
a
The alpha channel value of the vertex, where 1.0 represents opacity and 0.0 represents complete transparency.
You use texture vertices to define triangles to which a texture is to be mapped. A texture vertex is defined by the TQAVTexture data structure, which specifies the position, depth, transparency, and texture mapping information.

Note
Not all the fields of a TQAVTexture data structure need to be filled out. Many of these fields are used only when texture mapping operations are in force (that is, when the kQATag_TextureOp state variable has some value other than kQATextureOp_None).
typedef struct TQAVTexture {
   float                      x;
   float                      y;
   float                      z;
   float                      invW;
   float                      r;
   float                      g;
   float                      b;
   float                      a;
   float                      uOverW;
   float                      vOverW;
   float                      kd_r;
   float                      kd_g;
   float                      kd_b;
   float                      ks_r;
   float                      ks_g;
   float                      ks_b;
} TQAVTexture;
Field Description

x
The x coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
y
The y coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
z
The depth of the vertex. The value of this field is a floating-point number between 0.0 and 1.0 inclusive, where lower numbers specify points closer to the origin.
invW
The inverse w value (that is, the value 1/w, where w is the homogeneous correction factor). This field must contain a value. For drawing engines that support the kQAOptional_PerspectiveZ feature and when the state variable kQATag_PerspectiveZ is set to kQAPerspectiveZ_On, hidden surface removal is performed using the value in this field rather than the value in the z field. For non-perspective rendering, this field should be set to 1.0.
r
The red component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
g
The green component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
b
The blue component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
a
The alpha channel value of the vertex, where 1.0 represents opacity and 0.0 represents complete transparency.
uOverW
The perspective-corrected u coordinate of the vertex.
vOverW
The perspective-corrected v coordinate of the vertex.
kd_r
The red component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
kd_g
The green component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
kd_b
The blue component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
ks_r
The red component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.
ks_g
The green component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.
ks_b
The blue component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.
IMPORTANT
A drawing engine may choose to use a single modulation value instead of the three values kd_r, kd_g, and kd_b. This change is transparent to applications, except that colored lights applied to a texture appear white. As a result, a drawing engine that uses this simplification must negate the kQAOptional_TextureColor bit in the optional features value returned by QAEngineGestalt. Similarly, a drawing engine may choose to use a single highlight value instead of the three values ks_r, ks_g, and ks_b. This change is transparent to applications, except that a texture-mapped object's specular highlight appears white, not colored. As a result, a drawing engine that uses this simplification must negate the kQAOptional_TextureColor bit in the optional features value.