vpWindowPHIGS(3)

💅 vpWindowPHIGS 💅 (from the Library Functions Manual, bestie)

okay so this is the page for vpWindowPHIGS, and ngl it's giving "camera setup but make it PHIGS". let's get into it 🎀

---

✨ NAME ✨

vpWindowPHIGS — multiply the projection matrix by a PHIGS viewing matrix 🦋

---

🌸 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 you got from vpCreateContext. your main character ✨
• vrp — point specifying 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 (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 — projection type code. rn it must be VP_PARALLEL, no other option, periodt 💀

---

💜 DESCRIPTION 💜

vpWindowPHIGS multiplies the current projection matrix by a viewing-and-projection matrix that you specify using the PHIGS viewing model. this model is iconic because it bundles the viewpoint, the projection and the clipping parameters into one glow-up. the resulting matrix lands in the projection transformation matrix. and because both the view and the projection live in that one matrix, you normally don't use the view transformation matrix alongside vpWindowPHIGS — set it to the identity, fr fr. also, right now only parallel projections can be specified. if you want a different view specification model, go look at vpWindow(3), she's got her own thing going on ✨

assuming the view transformation matrix is the identity, the matrix that vpWindowPHIGS produces should transform world coordinates into clip coordinates. so here's the whole transformation, step by step, no gatekeeping:

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

next, a coordinate system called the view reference coordinate (VRC) system is specified by means of the view plane normal and the view up vector, vup. the origin of VRC coordinates is the view reference point. 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 used 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 from the center of the clipping window to the projection reference point (prp), which is also specified in VRC coordinates. finally, the front and back clipping planes are given by n=front and n=back in VRC coordinates. slay 🎀

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

---

🌈 STATE VARIABLES 🌈

the current matrix concatenation parameters can be retrieved with the following state variable codes (see vpGeti(3)): VP_CONCAT_MODE. 👑

---

💀 ERRORS 💀

the normal return value is VP_OK. the following error return values are possible:

• VPERROR_BAD_VALUE — the clipping plane coordinates are invalid (umin >= umax, etc.). 😭
• 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. not the vibe, bestie 💅

heads up: those clipping window bounds have to actually make sense — umin >= umax and friends will get you a VPERROR_BAD_VALUE, no cap.

---

👀 SEE ALSO 👀

VolPack(3), vpCreateContext(3), vpCurrentMatrix(3), vpWindow(3)

---

and that's the whole page, bestie 🫶 this one comes to you from the VolPack era of the manual pages — shoutout to VolPack for keeping it iconic, vpWindowPHIGS(3) forever 💖✨