vpWindowPHIGS(3)

💖 vpWindowPHIGS 💖

okay bestie, so this is a page from the VolPack library functions manual — that's the VolPack(3) manual, section 3, library functions. pull up a chair 🫶

---

✨ NAME ✨

vpWindowPHIGS — multiply the projection matrix by a PHIGS viewing matrix

it's giving "glow up your projection matrix with a whole PHIGS viewing model" and honestly? iconic 💅

---

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpWindowPHIGS(vpc, vrp, vpn, vup, prp, umin, umax, vmin, vmax, front,
        back, projection_type)
    vpContext *vpc;
    vpVector3 vrp, vpn, vup;
    vpVector3 prp;
    double umin, umax, vmin, vmax, front, back;
    int projection_type;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context, and yes it comes straight from vpCreateContext. no context, no vibes 😌
• vrp — point that specifies the view reference point.
• vpn — vector specifying the view plane normal.
• vup — vector specifying the view up vector.
• prp — point specifying the projection reference point, and it lives in view reference coordinates.
• umin — left coordinate of the clipping window (in view reference coordinates).
• umax — right coordinate of the clipping window (in view reference coordinates).
• vmin — bottom coordinate of the clipping window (in view reference coordinates).
• vmax — top coordinate of the clipping window (in view reference coordinates).
• front — coordinate of the near depth clipping plane (in view reference coordinates).
• back — coordinate of the far depth clipping plane (in view reference coordinates).
• projection_type — the projection type code. and listen, currently it must be VP_PARALLEL. that's the whole menu, bestie 🍓

---

💫 DESCRIPTION 💫

so vpWindowPHIGS takes your current projection matrix and multiplies it by a viewing-and-projection matrix that you spec out using the PHIGS viewing model. that model bundles the viewpoint, the projection and the clipping parameters all into one glow-up ✨ the resulting matrix gets stored in the projection transformation matrix.

and here's the thing — since the view and the projection both live in this one single matrix, you'd normally not use the view transformation matrix alongside vpWindowPHIGS. set it to the identity, periodt. right now only parallel projections are allowed. if you want a different view specification model, go see vpWindow(3).

okay so assuming the view transformation matrix is the identity, the matrix vpWindowPHIGS spits out should transform world coordinates into clip coordinates. here's how that transformation gets specified:

first, the projection plane (aka the view plane) is defined by a point on the plane — that's the view reference point, vrp — and a vector normal to the plane, which is the view plane normal, vpn. 🦋

next, a coordinate system called the view reference coordinate (VRC) system is specified using the view plane normal and the view up vector, vup. the origin of VRC coordinates is the view reference point. and the basis vectors of VRC coordinates are:

u = v cross n
v = the projection of vup parallel to vpn onto the view plane
n = vpn

this coordinate system is what you use to specify the direction of projection and the clipping window. 📐

the clipping window bounds in the projection plane are given by umin, umax, vmin and vmax. the direction of projection is the vector going from the center of the clipping window to the projection reference point (prp) — and prp is also specified in VRC coordinates. finally, the front and back clipping planes are given by n=front and n=back in VRC coordinates. 💀 it's a lot but you're doing amazing, keep going.

for a more detailed explanation of this view specification model, go read Computer Graphics: Principles and Practice by Foley, vanDam, Feiner and Hughes. study material, bestie 📚

---

🔮 STATE VARIABLES 🔮

you can retrieve the current matrix concatenation parameters with the following state variable codes (peep vpGeti(3)):

• VP_CONCAT_MODE

---

🚨 ERRORS 🚨

the normal return value is VP_OK. 💚 the following error return values are possible though, so brace yourself:

• VPERROR_BAD_VALUE — the clipping plane coordinates are invalid (umin >= umax, etc.). the math said no 🙈
• VPERROR_BAD_OPTION — the type argument is invalid.
• VPERROR_SINGULAR — the vectors defining view reference coordinates are not mutually orthogonal, or the projection reference point lies in the view plane. it's giving collapse 😭

---

👑 SEE ALSO 👑

• VolPack(3)
• vpCreateContext(3)
• vpCurrentMatrix(3)
• vpWindow(3)

---

and that's the whole page, bestie 🫶 this came out of the VolPack library manual, vpWindowPHIGS(3), and yeah — that's the source and the version right there. no date on this one, so we're just repping VolPack itself 💖 go forth and multiply those matrices, you absolute legend ⭐🧚💜