asgardius/virtualx-engine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #14365 from willnationsdev/camera-docs

Browse source 
[DOCS] Camera property changes
This commit is contained in:
Rémi Verschelde 2017-12-16 14:23:44 +01:00 committed by GitHub
commit 0f188461c5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 132 additions and 261 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

182
doc/classes/Camera.xml
View file

@ -25,88 +25,6 @@
Get the camera transform. Subclassed cameras (such as CharacterCamera) may provide different transforms than the [Node] transform.
</description>
</method>
<method name="get_cull_mask" qualifiers="const">
<return type="int">
</return>
<description>
Returns the culling mask, describing which 3D render layers are rendered by this Camera.
</description>
</method>
<method name="get_doppler_tracking" qualifiers="const">
<return type="int" enum="Camera.DopplerTracking">
</return>
<description>
</description>
</method>
<method name="get_environment" qualifiers="const">
<return type="Environment">
</return>
<description>
Returns the [Environment] used by this Camera.
</description>
</method>
<method name="get_fov" qualifiers="const">
<return type="float">
</return>
<description>
Returns the [i]FOV[/i] Y angle in degrees (FOV means Field of View).
</description>
</method>
<method name="get_h_offset" qualifiers="const">
<return type="float">
</return>
<description>
Returns the horizontal (X) offset of the Camera viewport.
</description>
</method>
<method name="get_keep_aspect_mode" qualifiers="const">
<return type="int" enum="Camera.KeepAspect">
</return>
<description>
Returns the current mode for keeping the aspect ratio. See [code]KEEP_*[/code] constants.
</description>
</method>
<method name="get_projection" qualifiers="const">
<return type="int" enum="Camera.Projection">
</return>
<description>
Returns the Camera's projection. See PROJECTION_* constants.
</description>
</method>
<method name="get_size" qualifiers="const">
<return type="float">
</return>
<description>
</description>
</method>
<method name="get_v_offset" qualifiers="const">
<return type="float">
</return>
<description>
Returns the vertical (Y) offset of the Camera viewport.
</description>
</method>
<method name="get_zfar" qualifiers="const">
<return type="float">
</return>
<description>
Returns the far clip plane in world space units.
</description>
</method>
<method name="get_znear" qualifiers="const">
<return type="float">
</return>
<description>
Returns the near clip plane in world space units.
</description>
</method>
<method name="is_current" qualifiers="const">
<return type="bool">
</return>
<description>
Returns [code]true[/code] if the Camera is the current one in the [Viewport], or plans to become current (if outside the scene tree).
</description>
</method>
<method name="is_position_behind" qualifiers="const">
<return type="bool">
</return>
@ -129,6 +47,7 @@
<argument index="0" name="screen_point" type="Vector2">
</argument>
<description>
Returns a normal vector from the screen point location directed along the camera. Orthogonal cameras are normalized. Perspective cameras account for perspective, screen width/height, etc.
</description>
</method>
<method name="project_position" qualifiers="const">
@ -158,51 +77,6 @@
Returns a 3D position in worldspace, that is the result of projecting a point on the [Viewport] rectangle by the camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking.
</description>
</method>
<method name="set_cull_mask">
<return type="void">
</return>
<argument index="0" name="mask" type="int">
</argument>
<description>
Sets the cull mask, describing which 3D render layers are rendered by this Camera.
</description>
</method>
<method name="set_doppler_tracking">
<return type="void">
</return>
<argument index="0" name="mode" type="int" enum="Camera.DopplerTracking">
</argument>
<description>
Changes Doppler effect tracking. See [code]DOPPLER_*[/code] constants.
</description>
</method>
<method name="set_environment">
<return type="void">
</return>
<argument index="0" name="env" type="Environment">
</argument>
<description>
Sets the [Environment] to use for this Camera.
</description>
</method>
<method name="set_h_offset">
<return type="void">
</return>
<argument index="0" name="ofs" type="float">
</argument>
<description>
Sets the horizontal (X) offset of the Camera viewport.
</description>
</method>
<method name="set_keep_aspect_mode">
<return type="void">
</return>
<argument index="0" name="mode" type="int" enum="Camera.KeepAspect">
</argument>
<description>
Sets the mode for keeping the aspect ratio. See [code]KEEP_*[/code] constants.
</description>
</method>
<method name="set_orthogonal">
<return type="void">
</return>
@ -229,15 +103,6 @@
Set the camera projection to perspective mode, by specifying a [i]FOV[/i] Y angle in degrees (FOV means Field of View), and the [i]near[/i] and [i]far[/i] clip planes in worldspace units.
</description>
</method>
<method name="set_v_offset">
<return type="void">
</return>
<argument index="0" name="ofs" type="float">
</argument>
<description>
Sets the vertical (Y) offset of the Camera viewport.
</description>
</method>
<method name="unproject_position" qualifiers="const">
<return type="Vector2">
</return>
@ -248,6 +113,47 @@
</description>
</method>
</methods>
<members>
<member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask">
The culling mask that describes which 3D render layers are rendered by this camera.
</member>
<member name="current" type="bool" setter="set_current" getter="is_current">
If [code]true[/code] the ancestor [Viewport] is currently using this Camera. Default value: [code]false[/code].
</member>
<member name="doppler_tracking" type="int" setter="set_doppler_tracking" getter="get_doppler_tracking" enum="Camera.DopplerTracking">
If not [code]DOPPLER_TRACKING_DISABLED[/code] this Camera will simulate the Doppler effect for objects changed in particular [code]_process[/code] methods. Default value: [code]DOPPLER_TRACKING_DISABLED[/code].
</member>
<member name="environment" type="Environment" setter="set_environment" getter="get_environment">
Set the [Environment] to use for this Camera.
</member>
<member name="far" type="float" setter="set_zfar" getter="get_zfar">
The distance to the far culling boundary for this Camera relative to its local z-axis.
</member>
<member name="fov" type="float" setter="set_fov" getter="get_fov">
The camera's field of view angle (in degrees). Only applicable in perspective mode. Since [member keep_aspect] locks one axis, [code]fov[/code] sets the other axis' field of view angle.
</member>
<member name="h_offset" type="float" setter="set_h_offset" getter="get_h_offset">
The horizontal (X) offset of the Camear viewport.
</member>
<member name="keep_aspect" type="int" setter="set_keep_aspect_mode" getter="get_keep_aspect_mode" enum="Camera.KeepAspect">
The axis to lock during [member fov]/[member size] adjustments.
</member>
<member name="near" type="float" setter="set_znear" getter="get_znear">
The distance to the near culling boundary for this Camera relative to its local z-axis.
</member>
<member name="projection" type="int" setter="set_projection" getter="get_projection" enum="Camera.Projection">
The camera's projection mode. In [code]PROJECTION_PERSPECTIVE[/code] mode, objects' z-distance from the camera's local space scales their perceived size.
</member>
<member name="size" type="float" setter="set_size" getter="get_size">
The camera's size measured as 1/2 the width or height. Only applicable in orthogonal mode. Since [member keep_aspect] locks on axis, [code]size[/code] sets the other axis' size length.
</member>
<member name="v_offset" type="float" setter="set_v_offset" getter="get_v_offset">
The horizontal (Y) offset of the Camear viewport.
</member>
<member name="vaspect" type="bool" setter="set_vaspect" getter="get_vaspect">
A boolean representation of [member keep_aspect] in which [code]true[/code] is equivalent to [code]KEEP_WIDTH[/code].
</member>
</members>
<constants>
<constant name="PROJECTION_PERSPECTIVE" value="0" enum="Projection">
Perspective Projection (object's size on the screen becomes smaller when far away).
@ -256,10 +162,10 @@
Orthogonal Projection (objects remain the same size on the screen no matter how far away they are).
</constant>
<constant name="KEEP_WIDTH" value="0" enum="KeepAspect">
Try to keep the aspect ratio when scaling the Camera's viewport to the screen. If not possible, preserve the viewport's width by changing the height. Height is [code]sizey[/code] for orthographic projection, [code]fovy[/code] for perspective projection.
Preserves the horizontal aspect ratio.
</constant>
<constant name="KEEP_HEIGHT" value="1" enum="KeepAspect">
Try to keep the aspect ratio when scaling the Camera's viewport to the screen. If not possible, preserve the viewport's height by changing the width. Width is [code]sizex[/code] for orthographic projection, [code]fovx[/code] for perspective projection.
Preserves the vertical aspect ratio.
</constant>
<constant name="DOPPLER_TRACKING_DISABLED" value="0" enum="DopplerTracking">
Disable Doppler effect simulation (default).

198
scene/3d/camera.cpp
View file

@ -56,126 +56,16 @@ void Camera::_update_camera_mode() {
}
}
bool Camera::_set(const StringName &p_name, const Variant &p_value) {
bool changed_all = false;
if (p_name == "projection") {
int proj = p_value;
if (proj == PROJECTION_PERSPECTIVE)
mode = PROJECTION_PERSPECTIVE;
if (proj == PROJECTION_ORTHOGONAL)
mode = PROJECTION_ORTHOGONAL;
changed_all = true;
} else if (p_name == "fov" || p_name == "fovy" || p_name == "fovx")
fov = p_value;
else if (p_name == "size" || p_name == "sizex" || p_name == "sizey")
size = p_value;
else if (p_name == "near")
near = p_value;
else if (p_name == "far")
far = p_value;
else if (p_name == "keep_aspect")
set_keep_aspect_mode(KeepAspect(int(p_value)));
else if (p_name == "vaspect")
set_keep_aspect_mode(p_value ? KEEP_WIDTH : KEEP_HEIGHT);
else if (p_name == "h_offset")
h_offset = p_value;
else if (p_name == "v_offset")
v_offset = p_value;
else if (p_name == "current") {
if (p_value.operator bool()) {
make_current();
} else {
clear_current();
void Camera::_validate_property(PropertyInfo &p_property) const {
if (p_property.name == "fov") {
if (mode == PROJECTION_ORTHOGONAL) {
p_property.usage = PROPERTY_USAGE_NOEDITOR;
}
} else if (p_name == "cull_mask") {
set_cull_mask(p_value);
} else if (p_name == "environment") {
set_environment(p_value);
} else if (p_name == "doppler/tracking") {
set_doppler_tracking(DopplerTracking(int(p_value)));
} else
return false;
_update_camera_mode();
if (changed_all)
_change_notify();
return true;
}
bool Camera::_get(const StringName &p_name, Variant &r_ret) const {
if (p_name == "projection") {
r_ret = mode;
} else if (p_name == "fov" || p_name == "fovy" || p_name == "fovx")
r_ret = fov;
else if (p_name == "size" || p_name == "sizex" || p_name == "sizey")
r_ret = size;
else if (p_name == "near")
r_ret = near;
else if (p_name == "far")
r_ret = far;
else if (p_name == "keep_aspect")
r_ret = int(keep_aspect);
else if (p_name == "current") {
if (is_inside_tree() && get_tree()->is_node_being_edited(this)) {
r_ret = current;
} else {
r_ret = is_current();
} else if (p_property.name == "size") {
if (mode == PROJECTION_PERSPECTIVE) {
p_property.usage = PROPERTY_USAGE_NOEDITOR;
}
} else if (p_name == "cull_mask") {
r_ret = get_cull_mask();
} else if (p_name == "h_offset") {
r_ret = get_h_offset();
} else if (p_name == "v_offset") {
r_ret = get_v_offset();
} else if (p_name == "environment") {
r_ret = get_environment();
} else if (p_name == "doppler/tracking") {
r_ret = get_doppler_tracking();
} else
return false;
return true;
}
void Camera::_get_property_list(List<PropertyInfo> *p_list) const {
p_list->push_back(PropertyInfo(Variant::INT, "projection", PROPERTY_HINT_ENUM, "Perspective,Orthogonal"));
switch (mode) {
case PROJECTION_PERSPECTIVE: {
p_list->push_back(PropertyInfo(Variant::REAL, "fov", PROPERTY_HINT_RANGE, "1,179,0.1", PROPERTY_USAGE_NOEDITOR));
if (keep_aspect == KEEP_WIDTH)
p_list->push_back(PropertyInfo(Variant::REAL, "fovx", PROPERTY_HINT_RANGE, "1,179,0.1", PROPERTY_USAGE_EDITOR));
else
p_list->push_back(PropertyInfo(Variant::REAL, "fovy", PROPERTY_HINT_RANGE, "1,179,0.1", PROPERTY_USAGE_EDITOR));
} break;
case PROJECTION_ORTHOGONAL: {
p_list->push_back(PropertyInfo(Variant::REAL, "size", PROPERTY_HINT_RANGE, "1,16384,0.01", PROPERTY_USAGE_NOEDITOR));
if (keep_aspect == KEEP_WIDTH)
p_list->push_back(PropertyInfo(Variant::REAL, "sizex", PROPERTY_HINT_RANGE, "0.1,16384,0.01", PROPERTY_USAGE_EDITOR));
else
p_list->push_back(PropertyInfo(Variant::REAL, "sizey", PROPERTY_HINT_RANGE, "0.1,16384,0.01", PROPERTY_USAGE_EDITOR));
} break;
}
p_list->push_back(PropertyInfo(Variant::REAL, "near", PROPERTY_HINT_EXP_RANGE, "0.01,4096.0,0.01"));
p_list->push_back(PropertyInfo(Variant::REAL, "far", PROPERTY_HINT_EXP_RANGE, "0.01,4096.0,0.01"));
p_list->push_back(PropertyInfo(Variant::INT, "keep_aspect", PROPERTY_HINT_ENUM, "Keep Width,Keep Height"));
p_list->push_back(PropertyInfo(Variant::BOOL, "current"));
p_list->push_back(PropertyInfo(Variant::INT, "cull_mask", PROPERTY_HINT_LAYERS_3D_RENDER));
p_list->push_back(PropertyInfo(Variant::OBJECT, "environment", PROPERTY_HINT_RESOURCE_TYPE, "Environment"));
p_list->push_back(PropertyInfo(Variant::REAL, "h_offset"));
p_list->push_back(PropertyInfo(Variant::REAL, "v_offset"));
p_list->push_back(PropertyInfo(Variant::INT, "doppler/tracking", PROPERTY_HINT_ENUM, "Disabled,Idle,Physics"));
}
void Camera::_update_camera() {
@ -282,6 +172,14 @@ void Camera::set_orthogonal(float p_size, float p_z_near, float p_z_far) {
update_gizmo();
}
void Camera::set_projection(Camera::Projection p_mode) {
if (p_mode == PROJECTION_PERSPECTIVE || p_mode == PROJECTION_ORTHOGONAL) {
mode = p_mode;
_update_camera_mode();
_change_notify();
}
}
RID Camera::get_camera() const {
return camera;
@ -311,6 +209,14 @@ void Camera::clear_current() {
}
}
void Camera::set_current(bool p_current) {
if (p_current) {
make_current();
} else {
clear_current();
}
}
bool Camera::is_current() const {
if (is_inside_tree() && !get_tree()->is_node_being_edited(this)) {
@ -481,6 +387,7 @@ void Camera::set_environment(const Ref<Environment> &p_environment) {
VS::get_singleton()->camera_set_environment(camera, environment->get_rid());
else
VS::get_singleton()->camera_set_environment(camera, RID());
_update_camera_mode();
}
Ref<Environment> Camera::get_environment() const {
@ -489,10 +396,9 @@ Ref<Environment> Camera::get_environment() const {
}
void Camera::set_keep_aspect_mode(KeepAspect p_aspect) {
keep_aspect = p_aspect;
VisualServer::get_singleton()->camera_set_use_vertical_aspect(camera, p_aspect == KEEP_WIDTH);
_update_camera_mode();
_change_notify();
}
@ -501,6 +407,15 @@ Camera::KeepAspect Camera::get_keep_aspect_mode() const {
return keep_aspect;
}
void Camera::set_vaspect(bool p_vaspect) {
set_keep_aspect_mode(p_vaspect ? KEEP_WIDTH : KEEP_HEIGHT);
_update_camera_mode();
}
bool Camera::get_vaspect() const {
return keep_aspect == KEEP_HEIGHT;
}
void Camera::set_doppler_tracking(DopplerTracking p_tracking) {
if (doppler_tracking == p_tracking)
@ -511,6 +426,7 @@ void Camera::set_doppler_tracking(DopplerTracking p_tracking) {
velocity_tracker->set_track_physics_step(doppler_tracking == DOPPLER_TRACKING_PHYSICS_STEP);
velocity_tracker->reset(get_global_transform().origin);
}
_update_camera_mode();
}
Camera::DopplerTracking Camera::get_doppler_tracking() const {
@ -529,13 +445,19 @@ void Camera::_bind_methods() {
ClassDB::bind_method(D_METHOD("set_orthogonal", "size", "z_near", "z_far"), &Camera::set_orthogonal);
ClassDB::bind_method(D_METHOD("make_current"), &Camera::make_current);
ClassDB::bind_method(D_METHOD("clear_current"), &Camera::clear_current);
ClassDB::bind_method(D_METHOD("set_current"), &Camera::set_current);
ClassDB::bind_method(D_METHOD("is_current"), &Camera::is_current);
ClassDB::bind_method(D_METHOD("get_camera_transform"), &Camera::get_camera_transform);
ClassDB::bind_method(D_METHOD("get_fov"), &Camera::get_fov);
ClassDB::bind_method(D_METHOD("get_size"), &Camera::get_size);
ClassDB::bind_method(D_METHOD("get_zfar"), &Camera::get_zfar);
ClassDB::bind_method(D_METHOD("get_znear"), &Camera::get_znear);
ClassDB::bind_method(D_METHOD("set_fov"), &Camera::set_fov);
ClassDB::bind_method(D_METHOD("set_size"), &Camera::set_size);
ClassDB::bind_method(D_METHOD("set_zfar"), &Camera::set_zfar);
ClassDB::bind_method(D_METHOD("set_znear"), &Camera::set_znear);
ClassDB::bind_method(D_METHOD("get_projection"), &Camera::get_projection);
ClassDB::bind_method(D_METHOD("set_projection"), &Camera::set_projection);
ClassDB::bind_method(D_METHOD("set_h_offset", "ofs"), &Camera::set_h_offset);
ClassDB::bind_method(D_METHOD("get_h_offset"), &Camera::get_h_offset);
ClassDB::bind_method(D_METHOD("set_v_offset", "ofs"), &Camera::set_v_offset);
@ -546,10 +468,26 @@ void Camera::_bind_methods() {
ClassDB::bind_method(D_METHOD("get_environment"), &Camera::get_environment);
ClassDB::bind_method(D_METHOD("set_keep_aspect_mode", "mode"), &Camera::set_keep_aspect_mode);
ClassDB::bind_method(D_METHOD("get_keep_aspect_mode"), &Camera::get_keep_aspect_mode);
ClassDB::bind_method(D_METHOD("set_vaspect"), &Camera::set_vaspect);
ClassDB::bind_method(D_METHOD("get_vaspect"), &Camera::get_vaspect);
ClassDB::bind_method(D_METHOD("set_doppler_tracking", "mode"), &Camera::set_doppler_tracking);
ClassDB::bind_method(D_METHOD("get_doppler_tracking"), &Camera::get_doppler_tracking);
//ClassDB::bind_method(D_METHOD("_camera_make_current"),&Camera::_camera_make_current );
ADD_PROPERTY(PropertyInfo(Variant::INT, "keep_aspect", PROPERTY_HINT_ENUM, "Keep Width,Keep Height"), "set_keep_aspect_mode", "get_keep_aspect_mode");
ADD_PROPERTY(PropertyInfo(Variant::BOOL, "vaspect"), "set_vaspect", "get_vaspect");
ADD_PROPERTY(PropertyInfo(Variant::INT, "cull_mask", PROPERTY_HINT_LAYERS_3D_RENDER), "set_cull_mask", "get_cull_mask");
ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "environment", PROPERTY_HINT_RESOURCE_TYPE, "Environment"), "set_environment", "get_environment");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "h_offset"), "set_h_offset", "get_h_offset");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "v_offset"), "set_v_offset", "get_v_offset");
ADD_PROPERTY(PropertyInfo(Variant::INT, "doppler_tracking", PROPERTY_HINT_ENUM, "Disabled,Idle,Physics"), "set_doppler_tracking", "get_doppler_tracking");
ADD_PROPERTY(PropertyInfo(Variant::INT, "projection", PROPERTY_HINT_ENUM, "Perspective,Orthogonal"), "set_projection", "get_projection");
ADD_PROPERTY(PropertyInfo(Variant::BOOL, "current"), "set_current", "is_current");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "fov", PROPERTY_HINT_RANGE, "1,179,0.1"), "set_fov", "get_fov");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "size", PROPERTY_HINT_RANGE, "0.1,16384,0.01"), "set_size", "get_size");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "near"), "set_znear", "get_znear");
ADD_PROPERTY(PropertyInfo(Variant::REAL, "far"), "set_zfar", "get_zfar");
BIND_ENUM_CONSTANT(PROJECTION_PERSPECTIVE);
BIND_ENUM_CONSTANT(PROJECTION_ORTHOGONAL);
@ -586,10 +524,30 @@ Camera::Projection Camera::get_projection() const {
return mode;
}
void Camera::set_cull_mask(uint32_t p_layers) {
void Camera::set_fov(float p_fov) {
fov = p_fov;
_update_camera_mode();
}
void Camera::set_size(float p_size) {
size = p_size;
_update_camera_mode();
}
void Camera::set_znear(float p_znear) {
near = p_znear;
_update_camera_mode();
}
void Camera::set_zfar(float p_zfar) {
far = p_zfar;
_update_camera_mode();
}
void Camera::set_cull_mask(uint32_t p_layers) {
layers = p_layers;
VisualServer::get_singleton()->camera_set_cull_mask(camera, layers);
_update_camera_mode();
}
uint32_t Camera::get_cull_mask() const {

13
scene/3d/camera.h
View file

@ -95,10 +95,8 @@ protected:
virtual void _request_camera_update();
void _update_camera_mode();
bool _set(const StringName &p_name, const Variant &p_value);
bool _get(const StringName &p_name, Variant &r_ret) const;
void _get_property_list(List<PropertyInfo> *p_list) const;
void _notification(int p_what);
virtual void _validate_property(PropertyInfo &property) const;
static void _bind_methods();
@ -111,9 +109,11 @@ public:
void set_perspective(float p_fovy_degrees, float p_z_near, float p_z_far);
void set_orthogonal(float p_size, float p_z_near, float p_z_far);
void set_projection(Camera::Projection p_mode);
void make_current();
void clear_current();
void set_current(bool p_current);
bool is_current() const;
RID get_camera() const;
@ -124,6 +124,11 @@ public:
float get_znear() const;
Projection get_projection() const;
void set_fov(float p_fov);
void set_size(float p_size);
void set_zfar(float p_zfar);
void set_znear(float p_znear);
virtual Transform get_camera_transform() const;
Vector3 project_ray_normal(const Point2 &p_pos) const;
@ -143,6 +148,8 @@ public:
void set_keep_aspect_mode(KeepAspect p_aspect);
KeepAspect get_keep_aspect_mode() const;
void set_vaspect(bool p_vaspect);
bool get_vaspect() const;
void set_v_offset(float p_offset);
float get_v_offset() const;