geCamera
Description: Creation/Transformation/projection code for a camera
Source file: …\genesis3d\OpenSource\Source\CAMERA.h
Functions: ConvertWorldSpaceToCameraSpace, Create, Destroy, GetClippingRect, GetWorldSpaceVisXForm, GetWorldSpaceXForm, GetZScale, Project, ScreenPointToWorld, SetAttributes, SetWorldSpaceVisXForm, SetWorldSpaceXForm, SetZScale, Transform, TransformAndProject, TransformAndProjectArray, TransformAndProjectL, TransformAndProjectLArray, TransformArray
Types: geCamera
Additions with Genesis v1.6: FillDriverInfo, GetCameraSpaceVisXForm, GetCameraSpaceXForm, GetFarClipPlane, GetPov, GetVisPov, GetViewAngleXSinCos, GetViewAngleYSinCos, GetWidthHeight, ProjectAndClamp, ProjectZ, SetFarClipPlane, GetScale
Types:
typedef struct geCamera geCamera;
This object represents a viewport into a geWorld and is used to specify the view to be rendered.
Functions:
GENESISAPI geBoolean GENESISCC geCamera_ConvertWorldSpaceToCameraSpace(const geXForm3d* WXForm, geXForm3d* CXForm);
This function converts a world-space transform WXForm to a camera-space transform and returns it as CXForm.
GENESISAPI geCamera* GENESISCC geCamera_Create(geFloat Fov, const geRect* Rect);
This function creates a new geCamera object with a field-of-visions (in radians) of Fov and a rendering rectangle of Rect in screen coordinates.
Returns: the newly created geCamera object.
GENESISAPI void GENESISCC geCamera_Destroy(geCamera* *pCamera);
This function decreases the reference count of geCamera pCamera by one. If the reference count goes to zero all of its resources are freed.
Returns: nothing.
void geCamera_FillDriverInfo(geCamera* Camera);
GENESISAPI const geXForm3d* GENESISCC geCamera_GetCameraSpaceXForm(const geCamera* Camera);
Added for Genesis3D v1.6
GENESISAPI const geXForm3d* GENESISCC geCamera_GetCameraSpaceVisXForm(const geCamera* Camera);
Added for Genesis3D v1.6
GENESISAPI void GENESISCC geCamera_GetClippingRect(const geCamera* Camera, geRect* Rect);
This function returns the clipping rectangle for geCamera Camera in Rect.
Returns: nothing.
GENESISAPI void GENESISCC geCamera_GetFarClipPlane(const geCamera* Camera, geBoolean* Enable, geFloat* ZFar);
Added for Genesis3D v1.6
GENESISAPI const geVec3d* GENESISCC geCamera_GetPov(const geCamera* Camera);
Added for Genesis3D v1.6
geFloat GENESISCC geCamera_GetScale(const geCamera* Camera);
Added for Genesis3D v1.6
void GENESISCC geCamera_GetViewAngleXSinCos(const geCamera* Camera, geFloat* SinAngle, geFloat* CosAngle);
Added for Genesis3D v1.6
const geVec3d* GENESISCC geCamera_GetVisPov(const geCamera* Camera);
Added for Genesis3D v1.6
void GENESISCC geCamera_GetViewAngleYSinCos(const geCamera* Camera, geFloat* SinAngle, geFloat* CosAngle);
Added for Genesis3D v1.6
void GENESISCC geCamera_GetWidthHeight(const geCamera* Camera, geFloat* Width, geFloat* Height);
Added for Genesis3D v1.6
GENESISAPI const geXForm3d* GENESISCC geCamera_GetWorldSpaceVisXForm(const geCamera* Camera);
This function returns the the vis transform of geCamera Camera. The vis transform can be set separately from the camera's actual position to allow for positioning of the camera "outside" of the world geometry. Vis calculations must be made from "inside" the world geometry. So, by placing the the vis transform at an appropriate location "inside" the world geometry it is possible to generate a rendering with a camera positioned "outside" of the world geometry.
Returns: the transform.
GENESISAPI const geXForm3d* GENESISCC geCamera_GetWorldSpaceXForm(const geCamera* Camera);
This function returns the current transform for geCamera Camera.
Returns: the transform.
GENESISAPI geFloat GENESISCC geCamera_GetZScale(const geCamera* Camera);
This function returns the Z scale settting for geCamera Camera. As far as I can tell so far, this seems to affect Z-buffering. Decreasing the ZScale supposedly can help eliminate z-buffering problems on actor animations. I suspect it would degrade performance however.
Returns: the result.
GENESISAPI void GENESISCC geCamera_Project(const geCamera* Camera, const geVec3d* PointInCameraSpace, geVec3d* ProjectedPoint);
This function projects the point PointInCameraSpace of geCamera Camera into screen-space and returns the result in ProjeectPoint.
Returns: nothing.
void GENESISCC geCamera_ProjectAndClamp(const geCamera* Camera, const geVec3d* PointInCameraSpace, geVec3d* ProjectedPoint);
Added for Genesis3d v1.6
GENESISAPI void GENESISCC geCamera_ProjectZ(const geCamera* Camera, const geVec3d* PointInCameraSpace, geVec3d* ProjectedPoint);
Added for Genesis3d v1.6
GENESISAPI void GENESISCC geCamera_ScreenPointToWorld(const geCamera* Camera, int32 ScreenX, int32 ScreenY, geVec3d* Vector);
This function converts a point in screen-space (X,Y,Z) for geCamera Camera into a point in world-space Vector.
Returns: nothing. (However, output of function is put into Vector)
Notes: ScreenX and ScreenY are relative to rendering screen with (0,0) at top left corner. If screen is rendered in window mode, then these "screen" coordinates are really a client coordinates.
Notes: Vector is a vector that points in the direction indicated by ScreenX and ScreenY. One application for this might be that the user selects a desired object with a mouse cursor. Imagine, in 3d space, a line from the camera towards the object the user is trying to select. Because the engine is projecting a 3d space (the world or level) onto a 2d space (the screen), it will be impossible for this function to determine exactly which 3d point is wanted along this line-of-site line. Thus this function simply returns a short vector pointing in the correct direction. Extending this vector/line while checking for collisions will be required to find the actual object.
Notes: The vector is intended to be relative to the camera's position.
GENESISAPI void GENESISCC geCamera_SetAttributes(geCamera* Camera, geFloat Fov, const geRect* Rect);
This function sets the field-of-view Fov and screen rectangle Rect of geCamera Camera.
Returns: nothing.
GENESISAPI void GENESISCC geCamera_SetFarClipPlane(geCamera* Camera, geBoolean Enable, geFloat ZFar);
Added for Genesis3D v1.6
GENESISAPI geBoolean GENESISCC geCamera_SetWorldSpaceVisXForm(geCamera* Camera, const geXForm3d* XForm);
This function sets the vis transform for geCamera Camera to XForm. The vis transform can be set separately from the camera's actual position to allow for positioning of the camera "outside" of the world geometry. Vis calculations must be made from "inside" the world geometry. So, by placing the the vis transform at an appropriate location "inside" the world geometry it is possible to generate a rendering with a camera positioned "outside" of the world geometry.
GENESISAPI geBoolean GENESISCC geCamera_SetWorldSpaceXForm(geCamera* Camera, const geXForm3d* XForm);
This function sets the transform for geCamera Camera to XForm.
GENESISAPI void GENESISCC geCamera_SetZScale(geCamera* Camera, geFloat ZScale);
This function sets the Z scale setting for geCamer Camera to ZScale. As far as I can tell so far, this seems to affect Z-buffering. Decreasing the ZScale supposedly can help eliminate z-buffering problems on actor animations. I suspect it would degrade performance however.
Returns: nothing.
GENESISAPI void GENESISCC geCamera_Transform(const geCamera* Camera, const geVec3d* WorldSpacePoint, geVec3d* CameraSpacePoint);
This function transforms world-space point WorldSpacePoint into a camera-space point for geCamera Camera returning the result in CameraSpacePoint.
Returns: nothing.
GENESISAPI void GENESISCC geCamera_TransformAndProject(const geCamera* Camera, const geVec3d* Point, geVec3d* ProjectedPoint);
// project from *WORLD* space to projected space
// projected space is not right-handed.
// projection is onto x-y plane x is right, y is down, z is in
This function transforms world-space point Point into a projected-space point for geCamera Camera returning the result in ProjectedPoint. Projected-space is a right-handed space relative to the geCamera with +X to the right, +Y in the camera up direction, and +Z in the camera in direction. (I may have the definition of +Z reversed here.)
Returns: nothing.
GENESISAPI void GENESISCC geCamera_TransformAndProjectArray(const geCamera* Camera, const geVec3d* WorldSpacePointPtr, geVec3d* ProjectedSpacePointPtr, int count);
This function transforms an array count of world-space points in the array at WorldSpacePointPtr into projected-space points for geCamera Camera returning the result in an array at ProjectedSpacePointPtr. See geCamera_TransformAndProject for more details.
Returns: nothing.
GENESISAPI void GENESISCC geCamera_TransformAndProjectL(const geCamera* Camera, const GE_LVertex* Point, GE_LVertex* ProjectedPoint);
// project from *WORLD* space to projected space
// projected space is not right-handed.
// projection is onto x-y plane x is right, y is down, z is in
This function transforms a world-space lit point Point into a projected-space lit point for geCamerageCamera Camera returning the result in GE_TLVertex ProjectedPoint. I'm not sure what the logic is in having separate definitions for GE_LVertex and GE_TLVertex. They appear to be completely interchangeable except for the capitalization of (x,y,z).
Returns: nothing.
GENESISAPI void GENESISCC geCamera_TransformAndProjectLArray(const geCamera* Camera, const GE_LVertex* WorldSpacePointPtr, GE_LVertex* ProjectedSpacePointPtr, int count);
This function transforms an array of count world-space lit points in the array at WorldSpacePointPtr into an a array of projected-space lit points for geCamera Camera returning the result in GE_LVertex array ProjectedSpacePointPtr. I'm not sure what the logic is in having separate definitions for GE_LVertex and GE_TLVertex. They appear to be completely interchangeable except for the capitalization of (x,y,z).
Returns: nothing.
GENESISAPI void GENESISCC geCamera_TransformArray(const geCamera* Camera, const geVec3d* WorldSpacePointPtr, geVec3d* CameraSpacePointPtr, int count);
This function transforms an array of count world-space points in array WorldSpacePointPtr into an array of camera-space points for geCamera Camera returning the result in CameraSpacePointPtr.
Returns: nothing.