diff options
Diffstat (limited to 'source/blender/editors/include/ED_view3d.h')
| -rw-r--r-- | source/blender/editors/include/ED_view3d.h | 426 |
1 files changed, 413 insertions, 13 deletions
diff --git a/source/blender/editors/include/ED_view3d.h b/source/blender/editors/include/ED_view3d.h index 008ad5b3203..6c986d8efe1 100644 --- a/source/blender/editors/include/ED_view3d.h +++ b/source/blender/editors/include/ED_view3d.h @@ -107,6 +107,11 @@ void ED_view3d_background_color_get(const struct Scene *scene, bool ED_view3d_has_workbench_in_texture_color(const struct Scene *scene, const struct Object *ob, const struct View3D *v3d); +/** + * Cursor position in `r_cursor_co`, result in `r_cursor_co`, `mval` in region coords. + * + * \note cannot use `event->mval` here, called by #object_add(). + */ void ED_view3d_cursor3d_position(struct bContext *C, const int mval[2], const bool use_depth, @@ -124,11 +129,44 @@ void ED_view3d_cursor3d_update(struct bContext *C, struct Camera *ED_view3d_camera_data_get(struct View3D *v3d, struct RegionView3D *rv3d); +/** + * Calculate the view transformation matrix from RegionView3D input. + * The resulting matrix is equivalent to #RegionView3D.viewinv + * \param mat: The view 4x4 transformation matrix to calculate. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from ofs, normally from #RegionView3D.dist. + */ void ED_view3d_to_m4(float mat[4][4], const float ofs[3], const float quat[4], const float dist); +/** + * Set the view transformation from a 4x4 matrix. + * + * \param mat: The view 4x4 transformation matrix to assign. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs`, normally from #RegionView3D.dist. + */ void ED_view3d_from_m4(const float mat[4][4], float ofs[3], float quat[4], const float *dist); +/** + * Set the #RegionView3D members from an objects transformation and optionally lens. + * \param ob: The object to set the view to. + * \param ofs: The view offset to be set, normally from #RegionView3D.ofs. + * \param quat: The view rotation to be set, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs `to be set, normally from #RegionView3D.dist. + * \param lens: The view lens angle set for cameras and lights, normally from View3D.lens. + */ void ED_view3d_from_object( const struct Object *ob, float ofs[3], float quat[4], float *dist, float *lens); +/** + * Set the object transformation from #RegionView3D members. + * \param depsgraph: The depsgraph to get the evaluated object parent + * for the transformation calculation. + * \param ob: The object which has the transformation assigned. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs`, normally from #RegionView3D.dist. + */ void ED_view3d_to_object(const struct Depsgraph *depsgraph, struct Object *ob, const float ofs[3], @@ -140,14 +178,24 @@ bool ED_view3d_camera_to_view_selected(struct Main *bmain, const struct Scene *scene, struct Object *camera_ob); +/** + * Use to store the last view, before entering camera view. + */ void ED_view3d_lastview_store(struct RegionView3D *rv3d); /* Depth buffer */ typedef enum { + /** Redraw viewport without Grease Pencil and Annotations. */ V3D_DEPTH_NO_GPENCIL = 0, + /** Redraw viewport with Grease Pencil and Annotations only. */ V3D_DEPTH_GPENCIL_ONLY, + /** Redraw viewport with active object only. */ V3D_DEPTH_OBJECT_ONLY, + } eV3DDepthOverrideMode; +/** + * Redraw the viewport depth buffer. + */ void ED_view3d_depth_override(struct Depsgraph *depsgraph, struct ARegion *region, struct View3D *v3d, @@ -309,6 +357,7 @@ void ED_view3d_cursor_snap_draw_util(struct RegionView3D *rv3d, /* view3d_iterators.c */ /* foreach iterators */ + void meshobject_foreachScreenVert( struct ViewContext *vc, void (*func)(void *userData, struct MVert *eve, const float screen_co[2], int index), @@ -328,6 +377,10 @@ void mesh_foreachScreenEdge(struct ViewContext *vc, void *userData, const eV3DProjTest clip_flag); +/** + * A version of #mesh_foreachScreenEdge that clips the segment when + * there is a clipping bounding box. + */ void mesh_foreachScreenEdge_clip_bb_segment(struct ViewContext *vc, void (*func)(void *userData, struct BMEdge *eed, @@ -352,6 +405,9 @@ void nurbs_foreachScreenVert(struct ViewContext *vc, const float screen_co[2]), void *userData, const eV3DProjTest clip_flag); +/** + * #ED_view3d_init_mats_rv3d must be called first. + */ void mball_foreachScreenElem(struct ViewContext *vc, void (*func)(void *userData, struct MetaElem *ml, @@ -364,6 +420,9 @@ void lattice_foreachScreenVert(struct ViewContext *vc, const float screen_co[2]), void *userData, const eV3DProjTest clip_flag); +/** + * #ED_view3d_init_mats_rv3d must be called first. + */ void armature_foreachScreenBone(struct ViewContext *vc, void (*func)(void *userData, struct EditBone *ebone, @@ -371,6 +430,10 @@ void armature_foreachScreenBone(struct ViewContext *vc, const float screen_co_b[2]), void *userData, const eV3DProjTest clip_flag); + +/** + * ED_view3d_init_mats_rv3d must be called first. + */ void pose_foreachScreenBone(struct ViewContext *vc, void (*func)(void *userData, struct bPoseChannel *pchan, @@ -381,10 +444,17 @@ void pose_foreachScreenBone(struct ViewContext *vc, /* *** end iterators *** */ /* view3d_project.c */ + +/** + * \note use #ED_view3d_ob_project_mat_get to get the projection matrix + */ void ED_view3d_project_float_v2_m4(const struct ARegion *region, const float co[3], float r_co[2], float mat[4][4]); +/** + * \note use #ED_view3d_ob_project_mat_get to get projecting mat + */ void ED_view3d_project_float_v3_m4(const struct ARegion *region, const float co[3], float r_co[3], @@ -399,10 +469,12 @@ eV3DProjStatus ED_view3d_project_short_ex(const struct ARegion *region, const float co[3], short r_co[2], const eV3DProjTest flag); +/* --- short --- */ eV3DProjStatus ED_view3d_project_short_global(const struct ARegion *region, const float co[3], short r_co[2], const eV3DProjTest flag); +/* object space, use ED_view3d_init_mats_rv3d before calling */ eV3DProjStatus ED_view3d_project_short_object(const struct ARegion *region, const float co[3], short r_co[2], @@ -415,10 +487,12 @@ eV3DProjStatus ED_view3d_project_int_ex(const struct ARegion *region, const float co[3], int r_co[2], const eV3DProjTest flag); +/* --- int --- */ eV3DProjStatus ED_view3d_project_int_global(const struct ARegion *region, const float co[3], int r_co[2], const eV3DProjTest flag); +/* object space, use ED_view3d_init_mats_rv3d before calling */ eV3DProjStatus ED_view3d_project_int_object(const struct ARegion *region, const float co[3], int r_co[2], @@ -431,10 +505,14 @@ eV3DProjStatus ED_view3d_project_float_ex(const struct ARegion *region, const float co[3], float r_co[2], const eV3DProjTest flag); +/* --- float --- */ eV3DProjStatus ED_view3d_project_float_global(const struct ARegion *region, const float co[3], float r_co[2], const eV3DProjTest flag); +/** + * Object space, use #ED_view3d_init_mats_rv3d before calling. + */ eV3DProjStatus ED_view3d_project_float_object(const struct ARegion *region, const float co[3], float r_co[2], @@ -443,17 +521,52 @@ eV3DProjStatus ED_view3d_project_float_object(const struct ARegion *region, float ED_view3d_pixel_size(const struct RegionView3D *rv3d, const float co[3]); float ED_view3d_pixel_size_no_ui_scale(const struct RegionView3D *rv3d, const float co[3]); +/** + * Calculate a depth value from \a co, use with #ED_view3d_win_to_delta + */ float ED_view3d_calc_zfac(const struct RegionView3D *rv3d, const float co[3], bool *r_flip); +/** + * Calculate a depth value from `co` (result should only be used for comparison). + */ float ED_view3d_calc_depth_for_comparison(const struct RegionView3D *rv3d, const float co[3]); bool ED_view3d_clip_segment(const struct RegionView3D *rv3d, float ray_start[3], float ray_end[3]); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards mval. + * ray_start is clipped by the view near limit so points in front of it are always in view. + * In orthographic view the resulting ray_normal will match the view vector. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near clipping value). + * \param mval: The area relative 2d location (such as event->mval, converted into float[2]). + * \param r_ray_start: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * \param do_clip_planes: Optionally clip the start of the ray by the view clipping planes. + * \return success, false if the ray is totally clipped. + */ bool ED_view3d_win_to_ray_clipped(struct Depsgraph *depsgraph, const struct ARegion *region, const struct View3D *v3d, const float mval[2], - float ray_start[3], - float ray_normal[3], - const bool do_clip); + float r_ray_start[3], + float r_ray_normal[3], + const bool do_clip_planes); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards `mval`. + * ray_start is clipped by the view near limit so points in front of it are always in view. + * In orthographic view the resulting ray_normal will match the view vector. + * This version also returns the ray_co point of the ray on window plane, useful to fix precision + * issues especially with orthographic view, where default ray_start is set rather far away. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near clipping value). + * \param mval: The area relative 2d location (such as `event->mval`, converted into float[2]). + * \param r_ray_co: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * \param r_ray_start: The world-space starting point of the ray. + * \param do_clip_planes: Optionally clip the start of the ray by the view clipping planes. + * \return success, false if the ray is totally clipped. + */ bool ED_view3d_win_to_ray_clipped_ex(struct Depsgraph *depsgraph, const struct ARegion *region, const struct View3D *v3d, @@ -461,14 +574,39 @@ bool ED_view3d_win_to_ray_clipped_ex(struct Depsgraph *depsgraph, float r_ray_co[3], float r_ray_normal[3], float r_ray_start[3], - bool do_clip); + bool do_clip_planes); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards `mval`. + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as `event->mval`, converted into float[2]). + * \param r_ray_start: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * + * \note Ignores view near/far clipping, + * to take this into account use #ED_view3d_win_to_ray_clipped. + */ void ED_view3d_win_to_ray(const struct ARegion *region, const float mval[2], float r_ray_start[3], float r_ray_normal[3]); +/** + * Calculate a normalized 3d direction vector from the viewpoint towards a global location. + * In orthographic view the resulting vector will match the view vector. + * \param rv3d: The region (used for the window width and height). + * \param coord: The world-space location. + * \param vec: The resulting normalized vector. + */ void ED_view3d_global_to_vector(const struct RegionView3D *rv3d, const float coord[3], float vec[3]); +/** + * Calculate a 3d location from 2d window coordinates. + * \param region: The region (used for the window width and height). + * \param depth_pt: The reference location used to calculate the Z depth. + * \param mval: The area relative location (such as `event->mval` converted to floats). + * \param r_out: The resulting world-space location. + */ void ED_view3d_win_to_3d(const struct View3D *v3d, const struct ARegion *region, const float depth_pt[3], @@ -484,6 +622,13 @@ bool ED_view3d_win_to_3d_on_plane(const struct ARegion *region, const float mval[2], const bool do_clip, float r_out[3]); +/** + * A wrapper for #ED_view3d_win_to_3d_on_plane that projects onto \a plane_fallback + * then maps this back to \a plane. + * + * This is intended to be used when \a plane is orthogonal to the views Z axis where + * projecting the \a mval doesn't work well (or fail completely when exactly aligned). + */ bool ED_view3d_win_to_3d_on_plane_with_fallback(const struct ARegion *region, const float plane[4], const float mval[2], @@ -495,19 +640,64 @@ bool ED_view3d_win_to_3d_on_plane_int(const struct ARegion *region, const int mval[2], const bool do_clip, float r_out[3]); +/** + * Calculate a 3d difference vector from 2d window offset. + * note that #ED_view3d_calc_zfac() must be called first to determine + * the depth used to calculate the delta. + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d difference (such as `event->mval[0] - other_x`). + * \param out: The resulting world-space delta. + */ void ED_view3d_win_to_delta(const struct ARegion *region, const float mval[2], float out[3], const float zfac); +/** + * Calculate a 3d origin from 2d window coordinates. + * \note Orthographic views have a less obvious origin, + * Since far clip can be a very large value resulting in numeric precision issues, + * the origin in this case is close to zero coordinate. + * + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as event->mval converted to floats). + * \param out: The resulting normalized world-space direction vector. + */ void ED_view3d_win_to_origin(const struct ARegion *region, const float mval[2], float out[3]); +/** + * Calculate a 3d direction vector from 2d window coordinates. + * This direction vector starts and the view in the direction of the 2d window coordinates. + * In orthographic view all window coordinates yield the same vector. + * + * \note doesn't rely on ED_view3d_calc_zfac + * for perspective view, get the vector direction to + * the mouse cursor as a normalized vector. + * + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as event->mval converted to floats). + * \param out: The resulting normalized world-space direction vector. + */ void ED_view3d_win_to_vector(const struct ARegion *region, const float mval[2], float out[3]); +/** + * Calculate a 3d segment from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_end is a far point. + * ray_start and ray_end are clipped by the view near and far limits + * so points along this line are always in view. + * In orthographic view all resulting segments will be parallel. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near and far clipping range). + * \param mval: The area relative 2d location (such as event->mval, converted into float[2]). + * \param r_ray_start: The world-space starting point of the segment. + * \param r_ray_end: The world-space end point of the segment. + * \param do_clip_planes: Optionally clip the ray by the view clipping planes. + * \return success, false if the segment is totally clipped. + */ bool ED_view3d_win_to_segment_clipped(struct Depsgraph *depsgraph, const struct ARegion *region, struct View3D *v3d, const float mval[2], float r_ray_start[3], float r_ray_end[3], - const bool do_clip); + const bool do_clip_planes); void ED_view3d_ob_project_mat_get(const struct RegionView3D *v3d, const struct Object *ob, float r_pmat[4][4]); @@ -515,6 +705,10 @@ void ED_view3d_ob_project_mat_get_from_obmat(const struct RegionView3D *rv3d, const float obmat[4][4], float r_pmat[4][4]); +/** + * Convert between region relative coordinates (x,y) and depth component z and + * a point in world space. + */ void ED_view3d_project_v3(const struct ARegion *region, const float world[3], float r_region_co[3]); @@ -527,6 +721,9 @@ bool ED_view3d_unproject_v3( /* end */ void ED_view3d_dist_range_get(const struct View3D *v3d, float r_dist_range[2]); +/** + * \note copies logic of #ED_view3d_viewplane_get(), keep in sync. + */ bool ED_view3d_clip_range_get(struct Depsgraph *depsgraph, const struct View3D *v3d, const struct RegionView3D *rv3d, @@ -543,6 +740,9 @@ bool ED_view3d_viewplane_get(struct Depsgraph *depsgraph, float *r_clipend, float *r_pixsize); +/** + * Use instead of: `GPU_polygon_offset(rv3d->dist, ...)` see bug T37727. + */ void ED_view3d_polygon_offset(const struct RegionView3D *rv3d, const float dist); void ED_view3d_calc_camera_border(const struct Scene *scene, @@ -572,15 +772,61 @@ void ED_view3d_clipping_calc(struct BoundBox *bb, const struct ARegion *region, const struct Object *ob, const struct rcti *rect); +/** + * Clamp min/max by the viewport clipping. + * + * \note This is an approximation, with the limitation that the bounding box from the (mix, max) + * calculation might not have any geometry inside the clipped region. + * Performing a clipping test on each vertex would work well enough for most cases, + * although it's not perfect either as edges/faces may intersect the clipping without having any + * of their vertices inside it. + * A more accurate result would be quite involved. + * + * \return True when the arguments were clamped. + */ bool ED_view3d_clipping_clamp_minmax(const struct RegionView3D *rv3d, float min[3], float max[3]); void ED_view3d_clipping_local(struct RegionView3D *rv3d, const float mat[4][4]); +/** + * Return true when `co` is hidden by the 3D views clipping planes. + * + * \param is_local: When true use local (object-space) #ED_view3d_clipping_local must run first, + * then all comparisons can be done in local-space. + * \return True when `co` is outside all clipping planes. + * + * \note Callers should check #RV3D_CLIPPING_ENABLED first. + */ bool ED_view3d_clipping_test(const struct RegionView3D *rv3d, const float co[3], const bool is_local); float ED_view3d_radius_to_dist_persp(const float angle, const float radius); float ED_view3d_radius_to_dist_ortho(const float lens, const float radius); +/** + * Return a new #RegionView3D.dist value to fit the \a radius. + * + * \note Depth isn't taken into account, this will fit a flat plane exactly, + * but points towards the view (with a perspective projection), + * may be within the radius but outside the view. eg: + * + * <pre> + * + + * pt --> + /^ radius + * / | + * / | + * view + + + * \ | + * \ | + * \| + * + + * </pre> + * + * \param region: Can be NULL if \a use_aspect is false. + * \param persp: Allow the caller to tell what kind of perspective to use (ortho/view/camera) + * \param use_aspect: Increase the distance to account for non 1:1 view aspect. + * \param radius: The radius will be fitted exactly, + * typically pre-scaled by a margin (#VIEW3D_MARGIN). + */ float ED_view3d_radius_to_dist(const struct View3D *v3d, const struct ARegion *region, const struct Depsgraph *depsgraph, @@ -588,12 +834,26 @@ float ED_view3d_radius_to_dist(const struct View3D *v3d, const bool use_aspect, const float radius); -/* Back-buffer select and draw support. */ +/** + * Back-buffer select and draw support. + */ void ED_view3d_backbuf_depth_validate(struct ViewContext *vc); +/** + * allow for small values [0.5 - 2.5], + * and large values, FLT_MAX by clamping by the area size + */ int ED_view3d_backbuf_sample_size_clamp(struct ARegion *region, const float dist); void ED_view3d_select_id_validate(struct ViewContext *vc); +/** + * Get the world-space 3d location from a screen-space 2d point. + * TODO: Implement #alphaoverride. We don't want to zoom into billboards. + * + * \param mval: Input screen-space pixel location. + * \param mouse_worldloc: Output world-space location. + * \param fallback_depth_pt: Use this points depth when no depth can be found. + */ bool ED_view3d_autodist(struct Depsgraph *depsgraph, struct ARegion *region, struct View3D *v3d, @@ -602,6 +862,9 @@ bool ED_view3d_autodist(struct Depsgraph *depsgraph, const bool alphaoverride, const float fallback_depth_pt[3]); +/** + * No 4x4 sampling, run #ED_view3d_depth_override first. + */ bool ED_view3d_autodist_simple(struct ARegion *region, const int mval[2], float mouse_worldloc[3], @@ -635,9 +898,21 @@ typedef enum { eV3DSelectObjectFilter ED_view3d_select_filter_from_mode(const struct Scene *scene, const struct Object *obact); +/** + * Optionally cache data for multiple calls to #view3d_opengl_select + * + * just avoid GPU_select headers outside this file + */ void view3d_opengl_select_cache_begin(void); void view3d_opengl_select_cache_end(void); +/** + * \warning be sure to account for a negative return value + * This is an error, "Too many objects in select buffer" + * and no action should be taken (can crash blender) if this happens + * + * \note (vc->obedit == NULL) can be set to explicitly skip edit-object selection. + */ int view3d_opengl_select_ex(struct ViewContext *vc, unsigned int *buffer, unsigned int bufsize, @@ -665,28 +940,57 @@ void ED_view3d_viewcontext_init(struct bContext *C, struct ViewContext *vc, struct Depsgraph *depsgraph); void ED_view3d_viewcontext_init_object(struct ViewContext *vc, struct Object *obact); +/** + * Use this call when executing an operator, + * event system doesn't set for each event the OpenGL drawing context. + */ void view3d_operator_needs_opengl(const struct bContext *C); void view3d_region_operator_needs_opengl(struct wmWindow *win, struct ARegion *region); -/* XXX should move to BLI_math */ +/** XXX: should move to BLI_math */ bool edge_inside_circle(const float cent[2], float radius, const float screen_co_a[2], const float screen_co_b[2]); -/* get 3d region from context, also if mouse is in header or toolbar */ +/** + * Get 3D region from context, also if mouse is in header or toolbar. + */ struct RegionView3D *ED_view3d_context_rv3d(struct bContext *C); +/** + * Ideally would return an rv3d but in some cases the region is needed too + * so return that, the caller can then access the `region->regiondata`. + */ bool ED_view3d_context_user_region(struct bContext *C, struct View3D **r_v3d, struct ARegion **r_region); +/** + * Similar to #ED_view3d_context_user_region() but does not use context. Always performs a lookup. + * Also works if \a v3d is not the active space. + */ bool ED_view3d_area_user_region(const struct ScrArea *area, const struct View3D *v3d, struct ARegion **r_region); bool ED_operator_rv3d_user_region_poll(struct bContext *C); +/** + * Most of the time this isn't needed since you could assume the view matrix was + * set while drawing, however when functions like mesh_foreachScreenVert are + * called by selection tools, we can't be sure this object was the last. + * + * for example, transparent objects are drawn after edit-mode and will cause + * the rv3d mat's to change and break selection. + * + * 'ED_view3d_init_mats_rv3d' should be called before + * view3d_project_short_clip and view3d_project_short_noclip in cases where + * these functions are not used during draw_object + */ void ED_view3d_init_mats_rv3d(const struct Object *ob, struct RegionView3D *rv3d); void ED_view3d_init_mats_rv3d_gl(const struct Object *ob, struct RegionView3D *rv3d); #ifdef DEBUG +/** + * Ensure we correctly initialize. + */ void ED_view3d_clear_mats_rv3d(struct RegionView3D *rv3d); void ED_view3d_check_mats_rv3d(struct RegionView3D *rv3d); #else @@ -705,6 +1009,9 @@ void ED_draw_object_facemap(struct Depsgraph *depsgraph, struct RenderEngineType *ED_view3d_engine_type(const struct Scene *scene, int drawtype); bool ED_view3d_context_activate(struct bContext *C); +/** + * Set the correct matrices + */ void ED_view3d_draw_setup_view(const struct wmWindowManager *wm, struct wmWindow *win, struct Depsgraph *depsgraph, @@ -715,13 +1022,22 @@ void ED_view3d_draw_setup_view(const struct wmWindowManager *wm, const float winmat[4][4], const struct rcti *rect); +/** + * `mval` comes from event->mval, only use within region handlers. + */ struct Base *ED_view3d_give_base_under_cursor(struct bContext *C, const int mval[2]); struct Object *ED_view3d_give_object_under_cursor(struct bContext *C, const int mval[2]); struct Object *ED_view3d_give_material_slot_under_cursor(struct bContext *C, const int mval[2], int *r_material_slot); bool ED_view3d_is_object_under_cursor(struct bContext *C, const int mval[2]); +/** + * 'clip' is used to know if our clip setting has changed. + */ void ED_view3d_quadview_update(struct ScrArea *area, struct ARegion *region, bool do_clip); +/** + * \note keep this synced with #ED_view3d_mats_rv3d_backup/#ED_view3d_mats_rv3d_restore + */ void ED_view3d_update_viewmat(struct Depsgraph *depsgraph, const struct Scene *scene, struct View3D *v3d, @@ -744,23 +1060,48 @@ void ED_view3d_datamask(const struct bContext *C, const struct Scene *scene, const struct View3D *v3d, struct CustomData_MeshMasks *r_cddata_masks); +/** + * Goes over all modes and view3d settings. + */ void ED_view3d_screen_datamask(const struct bContext *C, const struct Scene *scene, const struct bScreen *screen, struct CustomData_MeshMasks *r_cddata_masks); bool ED_view3d_offset_lock_check(const struct View3D *v3d, const struct RegionView3D *rv3d); +/** + * For viewport operators that exit camera perspective. + * + * \note This differs from simply setting `rv3d->persp = persp` because it + * sets the `ofs` and `dist` values of the viewport so it matches the camera, + * otherwise switching out of camera view may jump to a different part of the scene. + */ void ED_view3d_persp_switch_from_camera(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d, const char persp); +/** + * Action to take when rotating the view, + * handle auto-perspective and logic for switching out of views. + * + * shared with NDOF. + */ bool ED_view3d_persp_ensure(const struct Depsgraph *depsgraph, struct View3D *v3d, struct ARegion *region); -/* camera lock functions */ +/* Camera lock functions */ + +/** + * \return true when the 3D Viewport is locked to its camera. + */ bool ED_view3d_camera_lock_check(const struct View3D *v3d, const struct RegionView3D *rv3d); -/* copy the camera to the view before starting a view transformation */ +/** + * Copy the camera to the view before starting a view transformation. + * + * Apply the camera object transformation to the 3D Viewport. + * (needed so we can use regular 3D Viewport manipulation operators, that sync back to the camera). + */ void ED_view3d_camera_lock_init_ex(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d, @@ -768,7 +1109,13 @@ void ED_view3d_camera_lock_init_ex(const struct Depsgraph *depsgraph, void ED_view3d_camera_lock_init(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d); -/* copy the view to the camera, return true if */ +/** + * Copy the view to the camera, return true if. + * + * Apply the 3D Viewport transformation back to the camera object. + * + * \return true if the camera is moved. + */ bool ED_view3d_camera_lock_sync(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d); @@ -778,6 +1125,12 @@ bool ED_view3d_camera_autokey(const struct Scene *scene, struct bContext *C, const bool do_rotate, const bool do_translate); +/** + * Call after modifying a locked view. + * + * \note Not every view edit currently auto-keys (numeric-pad for eg), + * this is complicated because of smooth-view. + */ bool ED_view3d_camera_lock_autokey(struct View3D *v3d, struct RegionView3D *rv3d, struct bContext *C, @@ -789,14 +1142,41 @@ void ED_view3d_lock_clear(struct View3D *v3d); #define VIEW3D_MARGIN 1.4f #define VIEW3D_DIST_FALLBACK 1.0f +/** + * This function solves the problem of having to switch between camera and non-camera views. + * + * When viewing from the perspective of \a mat, and having the view center \a ofs, + * this calculates a distance from \a ofs to the matrix \a mat. + * Using \a fallback_dist when the distance would be too small. + * + * \param mat: A matrix use for the view-point (typically the camera objects matrix). + * \param ofs: Orbit center (negated), matching #RegionView3D.ofs, which is typically passed in. + * \param fallback_dist: The distance to use if the object is too near or in front of \a ofs. + * \returns A newly calculated distance or the fallback. + */ float ED_view3d_offset_distance(const float mat[4][4], const float ofs[3], const float fallback_dist); +/** + * Set the dist without moving the view (compensate with #RegionView3D.ofs) + * + * \note take care that #RegionView3d.viewinv is up to date, #ED_view3d_update_viewmat first. + */ void ED_view3d_distance_set(struct RegionView3D *rv3d, const float dist); +/** + * Change the distance & offset to match the depth of \a dist_co along the view axis. + * + * \param dist_co: A world-space location to use for the new depth. + * \param dist_min: Resulting distances below this will be ignored. + * \return Success if the distance was set. + */ bool ED_view3d_distance_set_from_location(struct RegionView3D *rv3d, const float dist_co[3], const float dist_min); +/** + * Could move this elsewhere, but tied into #ED_view3d_grid_scale + */ float ED_scene_grid_scale(const struct Scene *scene, const char **r_grid_unit); float ED_view3d_grid_scale(const struct Scene *scene, struct View3D *v3d, @@ -805,14 +1185,24 @@ void ED_view3d_grid_steps(const struct Scene *scene, struct View3D *v3d, struct RegionView3D *rv3d, float r_grid_steps[8]); +/** + * Simulates the grid scale that is actually viewed. + * The actual code is seen in `object_grid_frag.glsl` (see `grid_res`). + * Currently the simulation is only done when RV3D_VIEW_IS_AXIS. + */ float ED_view3d_grid_view_scale(struct Scene *scene, struct View3D *v3d, struct ARegion *region, const char **r_grid_unit); +/** + * \note The info that this uses is updated in #ED_refresh_viewport_fps, + * which currently gets called during #SCREEN_OT_animation_step. + */ void ED_scene_draw_fps(const struct Scene *scene, int xoffset, int *yoffset); -/* render */ +/* Render */ + void ED_view3d_stop_render_preview(struct wmWindowManager *wm, struct ARegion *region); void ED_view3d_shade_update(struct Main *bmain, struct View3D *v3d, struct ScrArea *area); @@ -825,7 +1215,10 @@ void ED_view3d_shade_update(struct Main *bmain, struct View3D *v3d, struct ScrAr #define XRAY_ACTIVE(v3d) (XRAY_ENABLED(v3d) && ((v3d)->shading.type < OB_MATERIAL)) /* view3d_draw_legacy.c */ -/* Try avoid using these more move out of legacy. */ + +/** + * Try avoid using these more move out of legacy. + */ void ED_view3d_draw_bgpic_test(const struct Scene *scene, struct Depsgraph *depsgraph, struct ARegion *region, @@ -834,6 +1227,7 @@ void ED_view3d_draw_bgpic_test(const struct Scene *scene, const bool do_camera_frame); /* view3d_gizmo_preselect_type.c */ + void ED_view3d_gizmo_mesh_preselect_get_active(struct bContext *C, struct wmGizmo *gz, struct Base **r_base, @@ -841,11 +1235,17 @@ void ED_view3d_gizmo_mesh_preselect_get_active(struct bContext *C, void ED_view3d_gizmo_mesh_preselect_clear(struct wmGizmo *gz); /* space_view3d.c */ + void ED_view3d_buttons_region_layout_ex(const struct bContext *C, struct ARegion *region, const char *category_override); /* view3d_view.c */ + +/** + * See if current UUID is valid, otherwise set a valid UUID to v3d, + * Try to keep the same UUID previously used to allow users to quickly toggle back and forth. + */ bool ED_view3d_local_collections_set(struct Main *bmain, struct View3D *v3d); void ED_view3d_local_collections_reset(struct bContext *C, const bool reset_all); |