< GeeXLab Reference Guide />
> Back to Reference Guide Index
gh_camera library
Description
gh_camera is the module that manages cameras: creation, destruction, setting the parameters (position, filed of view, etc.).
Number of functions: 43
- gh_camera.bind ()
- gh_camera.bind_v2 ()
- gh_camera.create_ortho ()
- gh_camera.create_orthographic ()
- gh_camera.create_persp ()
- gh_camera.create_persp_v2 ()
- gh_camera.create_persp_v3 ()
- gh_camera.create_perspective ()
- gh_camera.create_perspective_vk ()
- gh_camera.update_perspective_vk ()
- gh_camera.frustum_check_object_aa_box ()
- gh_camera.frustum_check_object_sphere ()
- gh_camera.frustum_check_point ()
- gh_camera.frustum_check_sphere ()
- gh_camera.frustum_update ()
- gh_camera.get_euler_angles ()
- gh_camera.get_fov ()
- gh_camera.get_position ()
- gh_camera.get_projection_matrix ()
- gh_camera.get_projection_matrix_4x4 ()
- gh_camera.get_up_vector ()
- gh_camera.get_view ()
- gh_camera.get_view_matrix ()
- gh_camera.get_view_quaternion ()
- gh_camera.load_gl2_matrix ()
- gh_camera.reset_reflection_matrix ()
- gh_camera.set_fov ()
- gh_camera.set_lookat ()
- gh_camera.set_orientation_cubemap ()
- gh_camera.set_pitch ()
- gh_camera.set_position ()
- gh_camera.set_projection_matrix ()
- gh_camera.set_reflection_matrix_v1 ()
- gh_camera.set_reflection_matrix_v2 ()
- gh_camera.set_reflection_matrix_v3 ()
- gh_camera.set_roll ()
- gh_camera.set_up_vec ()
- gh_camera.set_view_matrix ()
- gh_camera.set_viewport ()
- gh_camera.set_yaw ()
- gh_camera.update_ortho ()
- gh_camera.update_persp ()
- gh_camera.update_persp_v2 ()
bind
Description
Bind the camera to the renderer: the viewport and projection/view matrices are applied. This function is useful in conjunction with the gh_object.render() function.
Syntax
gh_camera.bind(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
This function has no return value(s).
Code sample
gh_camera.bind(camera)
bind_v2
Description
Bind the camera to the renderer: the viewport and projection/view matrices are applied. This function is useful in conjunction with the gh_object.render() function.
Syntax
gh_camera.bind_v2(
cam_id,
update_viewport,
update_scissor,
update_proj_mat,
update_view_mat,
update_fixed_pipeline
)
Languages
Parameters
- cam_id [ID]: camera identifier
- update_viewport [BOOLEAN]: updates the viewport: 1 (true) or 0 (false)
- update_scissor [BOOLEAN]: updates the scissor rectangle (same size than the viewport): 1 (true) or 0 (false)
- update_proj_mat [BOOLEAN]: updates the projection matrix: 1 (true) or 0 (false)
- update_view_mat [BOOLEAN]: updates the view matrix: 1 (true) or 0 (false)
- update_fixed_pipeline [BOOLEAN]: updates the fixed pipeline (so you will have access to gl_ModelViewProjectionMatrix in a vertex shader for example): 1 (true) or 0 (false)
Return Values
This function has no return value(s).
Code sample
local update_viewport = 1
local update_scissor = 0
local update_proj_mat = 1
local update_view_mat = 1
local update_fixed_pipeline = 0
gh_camera.bind_v2(cam_id, update_viewport, update_scissor, update_proj_mat, update_view_mat, update_fixed_pipeline)
create_ortho
Description
Creates an orthographic camera.
Syntax
cam_id = gh_camera.create_ortho(
left,
right,
bottom,
top,
znear,
zfar
)
Languages
Parameters
- left [REAL]: left clipping plane
- right [REAL]: right clipping plane
- bottom [REAL]: bottom clipping plane
- top [REAL]: top clipping plane
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
- cam_id [ID]: camera identifier
Code sample
w = screen_width
h = screen_height
cam_id = gh_camera.create_ortho(-w/2, w/2, -h/2, h/2, -1.0, 1.0)
create_orthographic
Description
Creates an orthographic camera with default values: left, right, top, bottom are derived from the window size.
Syntax
cam_id = gh_camera.create_orthographic()
Languages
Parameters
This function has no input parameter(s).
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_orthographic()
create_persp
Description
Creates a perspective camera.
Syntax
cam_id = gh_camera.create_persp(
fov,
aspect,
znear,
zfar
)
Languages
Parameters
- fov [REAL]: field of view in degres
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_persp(60, 1.333, 0.1, 1000.0)
create_persp_v2
Description
Creates a perspective camera.
Syntax
cam_id = gh_camera.create_persp_v2(
fov,
is_vertical_fov,
aspect,
znear,
zfar
)
Languages
Parameters
- fov [REAL]: field of view in degres
- is_vertical_fov [BOOLEAN]: 1 (vertical fov) or 0 (horizontal fov)
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_persp_v2(60, 1, 1.333, 0.1, 1000.0)
create_persp_v3
Description
Creates a perspective camera.
Syntax
cam_id = gh_camera.create_persp_v3(
fov_x,
fov_y,
aspect,
znear,
zfar
)
Languages
Parameters
- fov_x [REAL]: horizontal field of view in degres
- fov_y [REAL]: vertical field of view in degres
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_persp_v3(60, 70, 1.333, 0.1, 1000.0)
create_perspective
Description
Creates a perspective camera with default values (fov=60, znear=1, zfar=1000, aspect=win_width/win_height).
Syntax
cam_id = gh_camera.create_perspective(
pos_x, pos_y, pos_z,
lookat_x, lookat_y, lookat_z
)
Languages
Parameters
- pos_x, pos_y, pos_z [REAL]: position of the camera
- lookat_x, lookat_y, lookat_z [REAL]: look at point of the camera
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_perspective(0, 20, 0, 0, 0, 0)
create_perspective_vk
Description
Creates a perspective camera for Vulkan demos.
Syntax
cam_id = gh_camera.create_perspective_vk(
fov,
aspect,
znear,
zfar
)
Languages
Parameters
- fov [REAL]: field of view in degres
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
- cam_id [ID]: camera identifier
Code sample
cam_id = gh_camera.create_perspective_vk(60.0, winW/winH, 1.0, 1000.0)
update_perspective_vk
Description
Updates a perspective camera for Vulkan demos.
Syntax
gh_camera.update_perspective_vk(
cam_id,
fov,
aspect,
znear,
zfar
)
Languages
Parameters
- cam_id [ID]: camera identifier
- fov [REAL]: field of view in degres
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
This function has no return value(s).
Code sample
gh_camera.update_perspective_vk(cam_id, 60.0, winW/winH, 1.0, 1000.0)
frustum_check_object_aa_box
Description
Checks the collision between the camera frustum and the aligned bounding box of an object.
Syntax
collision = gh_camera.frustum_check_object_aa_box(
cam_id,
obj_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
- obj_id [ID]: object identifier
Return Values
- collision [BOOLEAN]: collision: 1 (true) or 0 (false)
Code sample
collision = gh_camera.frustum_check_object_aa_box(cam_id, obj_id)
frustum_check_object_sphere
Description
Checks the collision between the camera frustum and the bounding sphere of an object.
Syntax
collision = gh_camera.frustum_check_object_sphere(
cam_id,
obj_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
- obj_id [ID]: object identifier
Return Values
- collision [BOOLEAN]: collision: 1 (true) or 0 (false)
Code sample
collision = gh_camera.frustum_check_object_sphere(cam_id, obj_id)
frustum_check_point
Description
Checks the collision between the camera frustum and a point.
Syntax
collision = gh_camera.frustum_check_point(
cam_id,
x, y, z
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x, y, z [REAL]: position of the point
Return Values
- collision [BOOLEAN]: collision: 1 (true) or 0 (false)
Code sample
collision = gh_camera.frustum_check_point(cam_id, x, y, z)
frustum_check_sphere
Description
Checks the collision between the camera frustum and a sphere.
Syntax
collision = gh_camera.frustum_check_sphere(
cam_id,
x, y, z
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x, y, z [REAL]: position of the sphere center
Return Values
- collision [BOOLEAN]: collision: 1 (true) or 0 (false)
Code sample
collision = gh_camera.frustum_check_sphere(cam_id, radius, x, y, z)
frustum_update
Description
Updates the frustum volume of the camera. The frustum needs to be updated as soon as the camera view matrix has changed (position or orientation). Once the frustumn is updated, you can perform collision checks (frustum_check_sphere for example).
Syntax
gh_camera.frustum_update(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
This function has no return value(s).
Code sample
gh_camera.frustum_update(cam_id)
get_euler_angles
Description
Gets the Euler's angles.
Syntax
pitch, yaw, roll = gh_camera.get_euler_angles(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- pitch, yaw, roll [REAL]: Euler's angles in degrees
Code sample
pitch, yaw, roll = gh_camera.get_euler_angles(cam_id)
get_fov
Description
Gets the camera field of view (fov).
Syntax
fov = gh_camera.get_fov(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- fov [REAL]: vertical field of view in degrees
Code sample
fov = gh_camera.get_fov(cam_id)
get_position
Description
Gets the camera position.
Syntax
x, y, z = gh_camera.get_position(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
Code sample
x, y, z = gh_camera.get_position(cam_id)
get_projection_matrix
Description
Gets the camera projection matrix.
Syntax
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Code sample
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix(cam_id)
get_projection_matrix_4x4
Description
Gets the camera projection matrix.
Syntax
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix_4x4(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Code sample
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix_4x4(cam_id)
get_up_vector
Description
Gets the camera up vector (y axis).
Syntax
x, y, z = gh_camera.get_up_vector(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- x, y, z [REAL]: up vector
Code sample
x, y, z = gh_camera.get_up_vector(cam_id)
get_view
Description
Gets the camera direction (z axis or view vector).
Syntax
x, y, z = gh_camera.get_view(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- x, y, z [REAL]: view vector
Code sample
x, y, z = gh_camera.get_view(cam_id)
get_view_matrix
Description
Gets the camera view matrix.
Syntax
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_view_matrix(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Code sample
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_view_matrix(cam_id)
get_view_quaternion
Description
Gets the camera view quaternion.
Syntax
x, y, z, w = gh_camera.get_view_quaternion(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
- x, y, z, w [REAL]: view quaternion
Code sample
x, y, z, w = gh_camera.get_view_quaternion(cam_id)
load_gl2_matrix
Description
Loads matrices in the OpenGL 2 fixed pipeline.
Syntax
gh_camera.load_gl2_matrix(
cam_id,
load_proj_mat,
load_view_mat,
object_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
- load_proj_mat [BOOLEAN]: load the projection matrix (0 or 1)
- load_view_mat [BOOLEAN]: load the view matrix (0 or 1)
- object_id [ID]: object identifier
Return Values
This function has no return value(s).
Code sample
load_proj_mat = 1
load_view_mat = 1
gh_camera.load_gl2_matrix(cam_id, load_proj_mat, load_view_mat, object_id)
reset_reflection_matrix
Description
Resets the reflection matrix initialized by set_reflection_matrix_v1() or set_reflection_matrix_v2(). The reflection matrix is used in scenes where reflection effect (mirror) is required. When reflection rendering is done, you have to reset the reflection matrix.
Syntax
gh_camera.reset_reflection_matrix(
cam_id
)
Languages
Parameters
- cam_id [ID]: camera identifier
Return Values
This function has no return value(s).
Code sample
gh_camera.reset_reflection_matrix(cam_id)
set_fov
Description
Sets the camera field of view (fov).
Syntax
gh_camera.set_fov(
cam_id,
fov
)
Languages
Parameters
- cam_id [ID]: camera identifier
- fov [REAL]: vertical field of view in degrees
Return Values
This function has no return value(s).
Code sample
gh_camera.set_fov(cam_id, 90)
set_lookat
Description
Sets the camera look at point (what point in space the camera is looking).
Syntax
gh_camera.set_lookat(
cam_id,
x, y, z,
lookat_mode
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x, y, z [REAL]: the target
- lookat_mode [REAL]: 1: the target is a point (3D position) or 0: the target is a direction (3D vector)
Return Values
This function has no return value(s).
Code sample
-- Look at the center of the scene:
gh_camera.set_lookat(cam_id, 0, 0, 0, 1)
set_orientation_cubemap
Description
Sets the camera orientation according to a cubemap face.
Syntax
gh_camera.set_orientation_cubemap(
cam_id,
face
)
Languages
Parameters
- cam_id [ID]: camera identifier
- face [INTEGER]: cubemap face (0 to 5)
Return Values
This function has no return value(s).
Code sample
for face = 0, 5 do
gh_camera.set_orientation_cubemap(cam_id, face)
...
end
set_pitch
Description
Sets the camera pitch angle (x axis).
Syntax
gh_camera.set_pitch(
cam_id,
pitch
)
Languages
Parameters
- cam_id [ID]: camera identifier
- pitch [REAL]: pitch in degrees
Return Values
This function has no return value(s).
Code sample
gh_camera.set_pitch(cam_id, pitch)
set_position
Description
Sets the camera position.
Syntax
gh_camera.set_position(
cam_id,
x, y, z
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x, y, z [REAL]: 3D position of the camera
Return Values
This function has no return value(s).
Code sample
gh_camera.set_position(cam_id, 0, 10, 20)
set_projection_matrix
Description
Sets the camera projection matrix.
Syntax
gh_camera.set_projection_matrix(
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)
Languages
Parameters
- cam_id [ID]: camera identifier
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Return Values
This function has no return value(s).
Code sample
gh_camera.set_projection_matrix(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)
set_reflection_matrix_v1
Description
Sets / initializes the reflection matrix. The reflection matrix is used in scenes where reflection effect (mirror) is required. When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().
Syntax
gh_camera.set_reflection_matrix_v1(
cam_id,
px, py, pz,
nx, ny, nz,
y
)
Languages
Parameters
- cam_id [ID]: camera identifier
- px, py, pz [REAL]: mirror plane position
- nx, ny, nz [REAL]: mirror plane normal
- y [REAL]: y offset - default: 0
Return Values
This function has no return value(s).
Code sample
gh_camera.set_reflection_matrix_v1(cam_id, 0, 10, 0, 0, 0, 1)
set_reflection_matrix_v2
Description
Sets / initializes the reflection matrix. The reflection matrix is used in scenes where reflection effect (mirror) is required. When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().
Syntax
gh_camera.set_reflection_matrix_v2(
cam_id,
a, b, c, d
)
Languages
Parameters
- cam_id [ID]: camera identifier
- a, b, c, d [REAL]: mirror plane equation
Return Values
This function has no return value(s).
Code sample
a, b, c, d = gh_object.get_plane_equation(mirror_plane)
gh_camera.set_reflection_matrix_v2(cam_id, a, b, c, d)
set_reflection_matrix_v3
Description
Sets / initializes the reflection matrix. The reflection matrix is used in scenes where reflection effect (mirror) is required. When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().
Syntax
gh_camera.set_reflection_matrix_v3(
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)
Languages
Parameters
- cam_id [ID]: camera identifier
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Return Values
This function has no return value(s).
Code sample
gh_camera.set_reflection_matrix_v3(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)
set_roll
Description
Sets the camera roll angle (z axis).
Syntax
gh_camera.set_roll(
cam_id,
roll
)
Languages
Parameters
- cam_id [ID]: camera identifier
- roll [REAL]: roll in degrees
Return Values
This function has no return value(s).
Code sample
gh_camera.set_roll(cam_id, roll)
set_up_vec
Description
Sets the camera up vector.
Syntax
gh_camera.set_up_vec(
cam_id,
x, y, z
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x, y, z [REAL]: direction of the up vector
Return Values
This function has no return value(s).
Code sample
-- The up vector is the unit Y axis.
gh_camera.set_up_vec(cam_id, 0, 1, 0)
set_view_matrix
Description
Sets the camera view matrix.
Syntax
gh_camera.set_view_matrix(
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)
Languages
Parameters
- cam_id [ID]: camera identifier
- m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 [REAL]: the 16 floats that make the 4x4 matrix
Return Values
This function has no return value(s).
Code sample
gh_camera.set_view_matrix(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)
set_viewport
Description
Sets the camera viewport.
Syntax
gh_camera.set_viewport(
cam_id,
x,
y,
width,
height
)
Languages
Parameters
- cam_id [ID]: camera identifier
- x [INTEGER]: x offset - default: 0
- y [INTEGER]: y offset - default: 0
- width [INTEGER]: width of the viewport
- height [INTEGER]: height of the viewport
Return Values
This function has no return value(s).
Code sample
gh_camera.set_viewport(cam_id, 0, 0, screen_width, screen_height)
set_yaw
Description
Sets the camera yaw angle (y axis).
Syntax
gh_camera.set_yaw(
cam_id,
yaw
)
Languages
Parameters
- cam_id [ID]: camera identifier
- yaw [REAL]: yaw in degrees
Return Values
This function has no return value(s).
Code sample
gh_camera.set_yaw(cam_id, yaw)
update_ortho
Description
Updates an orthographic camera.
Syntax
gh_camera.update_ortho(
cam_id,
left,
right,
bottom,
top,
znear,
zfar
)
Languages
Parameters
- cam_id [ID]: camera identifier
- left [REAL]: left clipping plane
- right [REAL]: right clipping plane
- bottom [REAL]: bottom clipping plane
- top [REAL]: top clipping plane
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
This function has no return value(s).
Code sample
w = screen_width
h = screen_height
gh_camera.update_ortho(cam_id, -w/2, w/2, -h/2, h/2, 1.0, -1.0)
update_persp
Description
Updates a perspective camera.
Syntax
gh_camera.update_persp(
cam_id,
fov,
aspect,
znear,
zfar
)
Languages
Parameters
- cam_id [ID]: camera identifier
- fov [REAL]: field of view in degres
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
This function has no return value(s).
Code sample
gh_camera.update_persp(cam_id, 60, 1.333, 0.1, 1000.0)
update_persp_v2
Description
Updates a perspective camera.
Syntax
gh_camera.update_persp_v2(
cam_id,
fov,
is_vertical_fov,
aspect,
znear,
zfar
)
Languages
Parameters
- cam_id [ID]: camera identifier
- fov [REAL]: field of view in degres
- is_vertical_fov [BOOLEAN]: 1 (vertical fov) or 0 (horizontal fov)
- aspect [REAL]: aspect ratio (usually screen_width / screen_height)
- znear [REAL]: near clipping plane
- zfar [REAL]: far clipping plane
Return Values
This function has no return value(s).
Code sample
local is_vertical_fov = 1
gh_camera.update_persp_v2(cam_id, 60, is_vertical_fov, 1.333, 0.1, 1000.0)
| |