diff options
Diffstat (limited to 'source/blender/editors/include/ED_gpencil.h')
-rw-r--r-- | source/blender/editors/include/ED_gpencil.h | 266 |
1 files changed, 254 insertions, 12 deletions
diff --git a/source/blender/editors/include/ED_gpencil.h b/source/blender/editors/include/ED_gpencil.h index 1cf15ce3a48..53c55a7668f 100644 --- a/source/blender/editors/include/ED_gpencil.h +++ b/source/blender/editors/include/ED_gpencil.h @@ -116,42 +116,97 @@ typedef struct tGPspoint { /* ----------- Grease Pencil Tools/Context ------------- */ /* Context-dependent */ + +/** + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it. + */ struct bGPdata **ED_gpencil_data_get_pointers(const struct bContext *C, struct PointerRNA *r_ptr); +/** + * Get the active Grease Pencil data-block + */ struct bGPdata *ED_gpencil_data_get_active(const struct bContext *C); +/** + * Get the evaluated copy of the active Grease Pencil data-block (where applicable) + * - For the 3D View (i.e. "GP Objects"), this gives the evaluated copy of the GP data-block + * (i.e. a copy of the active GP data-block for the active object, where modifiers have been + * applied). This is needed to correctly work with "Copy-on-Write". + * - For all other editors (i.e. "GP Annotations"), this just gives the active data-block + * like for #ED_gpencil_data_get_active() + */ struct bGPdata *ED_gpencil_data_get_active_evaluated(const struct bContext *C); -/* Context independent (i.e. each required part is passed in instead) */ +/** + * Context independent (i.e. each required part is passed in instead). + * + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it, + * when context info is not available. + */ struct bGPdata **ED_gpencil_data_get_pointers_direct(struct ScrArea *area, struct Object *ob, struct PointerRNA *r_ptr); +/* Get the active Grease Pencil data-block, when context is not available */ struct bGPdata *ED_gpencil_data_get_active_direct(struct ScrArea *area, struct Object *ob); +/** + * Get the active Grease Pencil data-block + * \note This is the original (#G.main) copy of the data-block, stored in files. + * Do not use for reading evaluated copies of GP Objects data. + */ struct bGPdata *ED_annotation_data_get_active(const struct bContext *C); +/** + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it. + */ struct bGPdata **ED_annotation_data_get_pointers(const struct bContext *C, struct PointerRNA *r_ptr); +/** + * Get pointer to active Grease Pencil data-block for annotations, + * and an RNA-pointer to trace back to whatever owns it, + * when context info is not available. + */ struct bGPdata **ED_annotation_data_get_pointers_direct(struct ID *screen_id, struct ScrArea *area, struct Scene *scene, struct PointerRNA *r_ptr); +/** + * Get the active Grease Pencil data-block, when context is not available. + */ struct bGPdata *ED_annotation_data_get_active_direct(struct ID *screen_id, struct ScrArea *area, struct Scene *scene); +/** + * Utility to check whether the r_ptr output of ED_gpencil_data_get_pointers() + * is for annotation usage. + */ bool ED_gpencil_data_owner_is_annotation(struct PointerRNA *owner_ptr); /* 3D View */ + +/** + * Check whether there's an active GP keyframe on the current frame. + */ bool ED_gpencil_has_keyframe_v3d(struct Scene *scene, struct Object *ob, int cfra); /* ----------- Stroke Editing Utilities ---------------- */ bool ED_gpencil_frame_has_selected_stroke(const struct bGPDframe *gpf); bool ED_gpencil_layer_has_selected_stroke(const struct bGPDlayer *gpl, const bool is_multiedit); +/** + * Check whether given stroke can be edited given the supplied context. + * TODO: do we need additional flags for screen-space vs data-space?. + */ bool ED_gpencil_stroke_can_use_direct(const struct ScrArea *area, const struct bGPDstroke *gps); +/* Check whether given stroke can be edited in the current context */ bool ED_gpencil_stroke_can_use(const struct bContext *C, const struct bGPDstroke *gps); +/* Check whether given stroke can be edited for the current color */ bool ED_gpencil_stroke_material_editable(struct Object *ob, const struct bGPDlayer *gpl, const struct bGPDstroke *gps); +/* Check whether given stroke is visible for the current material. */ bool ED_gpencil_stroke_material_visible(struct Object *ob, const struct bGPDstroke *gps); /* ----------- Grease Pencil Operators ----------------- */ @@ -164,13 +219,32 @@ void ED_operatormacros_gpencil(void); /* ------------- Copy-Paste Buffers -------------------- */ /* Strokes copybuf */ + +/** + * Free copy/paste buffer data. + */ void ED_gpencil_strokes_copybuf_free(void); /* ------------ Grease-Pencil Drawing API ------------------ */ /* drawgpencil.c */ +/** + * Draw grease-pencil sketches to specified 2d-view that uses ibuf corrections. + */ void ED_annotation_draw_2dimage(const struct bContext *C); +/** + * Draw grease-pencil sketches to specified 2d-view + * assuming that matrices are already set correctly. + * + * \note This gets called twice - first time with onlyv2d=true to draw 'canvas' strokes, + * second time with onlyv2d=false for screen-aligned strokes. + */ void ED_annotation_draw_view2d(const struct bContext *C, bool onlyv2d); +/** + * Draw annotations sketches to specified 3d-view assuming that matrices are already set correctly. + * NOTE: this gets called twice - first time with only3d=true to draw 3d-strokes, + * second time with only3d=false for screen-aligned strokes. + */ void ED_annotation_draw_view3d(struct Scene *scene, struct Depsgraph *depsgraph, struct View3D *v3d, @@ -184,43 +258,103 @@ void ED_annotation_draw_ex(struct Scene *scene, const char spacetype); /* ----------- Grease-Pencil AnimEdit API ------------------ */ +/** + * Loops over the gp-frames for a gp-layer, and applies the given callback. + */ bool ED_gpencil_layer_frames_looper(struct bGPDlayer *gpl, struct Scene *scene, bool (*gpf_cb)(struct bGPDframe *, struct Scene *)); +/** + * Make a listing all the gp-frames in a layer as cfraelems. + */ void ED_gpencil_layer_make_cfra_list(struct bGPDlayer *gpl, ListBase *elems, bool onlysel); +/** + * Check if one of the frames in this layer is selected. + */ bool ED_gpencil_layer_frame_select_check(const struct bGPDlayer *gpl); +/** + * Set all/none/invert select. + */ void ED_gpencil_layer_frame_select_set(struct bGPDlayer *gpl, short mode); +/** + * Select the frames in this layer that occur within the bounds specified. + */ void ED_gpencil_layer_frames_select_box(struct bGPDlayer *gpl, float min, float max, short select_mode); +/** + * Select the frames in this layer that occur within the lasso/circle region specified. + */ void ED_gpencil_layer_frames_select_region(struct KeyframeEditData *ked, struct bGPDlayer *gpl, short tool, short select_mode); +/** + * Set all/none/invert select (like above, but with SELECT_* modes). + */ void ED_gpencil_select_frames(struct bGPDlayer *gpl, short select_mode); +/** + * Select the frame in this layer that occurs on this frame (there should only be one at most). + */ void ED_gpencil_select_frame(struct bGPDlayer *gpl, int selx, short select_mode); +/** + * Delete selected frames. + */ bool ED_gpencil_layer_frames_delete(struct bGPDlayer *gpl); +/** + * Duplicate selected frames from given gp-layer. + */ void ED_gpencil_layer_frames_duplicate(struct bGPDlayer *gpl); +/** + * Merge two layers. + */ void ED_gpencil_layer_merge(struct bGPdata *gpd, struct bGPDlayer *gpl_src, struct bGPDlayer *gpl_dst, const bool reverse); +/** + * Set keyframe type for selected frames from given gp-layer + * + * \param type: The type of keyframe (#eBezTriple_KeyframeType) to set selected frames to. + */ void ED_gpencil_layer_frames_keytype_set(struct bGPDlayer *gpl, short type); - +/** + * Snap selected frames to .... + */ void ED_gpencil_layer_snap_frames(struct bGPDlayer *gpl, struct Scene *scene, short mode); + +/** + * Mirror selected gp-frames on... + * TODO: mirror over a specific time. + */ void ED_gpencil_layer_mirror_frames(struct bGPDlayer *gpl, struct Scene *scene, short mode); +/** + * This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ED_gpencil_anim_copybuf_free(void); +/** + * This function adds data to the copy/paste buffer, freeing existing data first + * Only the selected GP-layers get their selected keyframes copied. + * + * Returns whether the copy operation was successful or not. + */ bool ED_gpencil_anim_copybuf_copy(struct bAnimContext *ac); +/** + * Pastes keyframes from buffer, and reports success. + */ bool ED_gpencil_anim_copybuf_paste(struct bAnimContext *ac, const short copy_mode); /* ------------ Grease-Pencil Undo System ------------------ */ int ED_gpencil_session_active(void); +/** + * \param step: eUndoStepDir. + */ int ED_undo_gpencil_step(struct bContext *C, const int step); /* eUndoStepDir. */ /* ------------ Grease-Pencil Armature ------------------ */ @@ -234,7 +368,10 @@ bool ED_gpencil_add_armature_weights(const struct bContext *C, struct Object *ob_arm, int mode); -/* Add Lattice modifier using Parent operator */ +/** + * Add Lattice modifier using Parent operator. + * Parent GPencil object to Lattice. + */ bool ED_gpencil_add_lattice_modifier(const struct bContext *C, struct ReportList *reports, struct Object *ob, @@ -246,37 +383,74 @@ bool ED_gpencil_add_lattice_modifier(const struct bContext *C, /* ------------ Transformation Utilities ------------ */ -/* reset parent matrix for all layers */ +/** + * Reset parent matrix for all layers. + */ void ED_gpencil_reset_layers_parent(struct Depsgraph *depsgraph, struct Object *obact, struct bGPdata *gpd); -/* cursor utilities */ +/* Cursor utilities. */ + +/** + * Draw eraser cursor. + */ void ED_gpencil_brush_draw_eraser(struct Brush *brush, int x, int y); /* ----------- Add Primitive Utilities -------------- */ -/* Number of values defining each point in the built-in data buffers for primitives. */ +/** Number of values defining each point in the built-in data buffers for primitives. */ #define GP_PRIM_DATABUF_SIZE 5 +/** + * Populate stroke with point data from data buffers. + * \param gps: Grease pencil stroke + * \param array: Flat array of point data values. Each entry has #GP_PRIM_DATABUF_SIZE values. + * \param totpoints: Total of points + * \param mat: 4x4 transform matrix to transform points into the right coordinate space. + */ void ED_gpencil_stroke_init_data(struct bGPDstroke *gps, const float *array, const int totpoints, const float mat[4][4]); +/** + * Add a Simple empty object with one layer and one color. + */ void ED_gpencil_create_blank(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a 2D Suzanne (original model created by Matias Mendiola). + */ void ED_gpencil_create_monkey(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a Simple stroke with colors + * (original design created by Daniel M. Lara and Matias Mendiola). + */ void ED_gpencil_create_stroke(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a Simple LineArt setup. + */ void ED_gpencil_create_lineart(struct bContext *C, struct Object *ob); /* ------------ Object Utilities ------------ */ +/** + * Helper function to create new #OB_GPENCIL Object. + */ struct Object *ED_gpencil_add_object(struct bContext *C, const float loc[3], unsigned short local_view_bits); +/** + * Helper function to create default colors and drawing brushes. + */ void ED_gpencil_add_defaults(struct bContext *C, struct Object *ob); -/* set object modes */ +/** + * Set object modes. + */ void ED_gpencil_setup_modes(struct bContext *C, struct bGPdata *gpd, int newmode); bool ED_object_gpencil_exit(struct Main *bmain, struct Object *ob); +/** + * Reproject all points of the stroke to a plane locked to axis to avoid stroke offset + */ void ED_gpencil_project_stroke_to_plane(const struct Scene *scene, const struct Object *ob, const struct RegionView3D *rv3d, @@ -284,6 +458,10 @@ void ED_gpencil_project_stroke_to_plane(const struct Scene *scene, struct bGPDstroke *gps, const float origin[3], const int axis); +/** + * Reproject given point to a plane locked to axis to avoid stroke offset + * \param pt: Point to affect (used for input & output). + */ void ED_gpencil_project_point_to_plane(const struct Scene *scene, const struct Object *ob, struct bGPDlayer *gpl, @@ -291,6 +469,10 @@ void ED_gpencil_project_point_to_plane(const struct Scene *scene, const float origin[3], const int axis, struct bGPDspoint *pt); +/** + * Get drawing reference point for conversion or projection of the stroke + * \param r_vec: Reference point found + */ void ED_gpencil_drawing_reference_get(const struct Scene *scene, const struct Object *ob, char align_flag, @@ -299,6 +481,9 @@ void ED_gpencil_project_stroke_to_view(struct bContext *C, struct bGPDlayer *gpl, struct bGPDstroke *gps); +/** + * Reproject selected strokes. + */ void ED_gpencil_stroke_reproject(struct Depsgraph *depsgraph, const struct GP_SpaceConversion *gsc, struct SnapObjectContext *sctx, @@ -308,27 +493,54 @@ void ED_gpencil_stroke_reproject(struct Depsgraph *depsgraph, const eGP_ReprojectModes mode, const bool keep_original); -/* set sculpt cursor */ +/** + * Turn brush cursor in on/off. + */ void ED_gpencil_toggle_brush_cursor(struct bContext *C, bool enable, void *customdata); /* vertex groups */ + +/** + * Assign points to vertex group. + */ void ED_gpencil_vgroup_assign(struct bContext *C, struct Object *ob, float weight); +/** + * Remove points from vertex group. + */ void ED_gpencil_vgroup_remove(struct bContext *C, struct Object *ob); +/** + * Select points of vertex group. + */ void ED_gpencil_vgroup_select(struct bContext *C, struct Object *ob); +/** + * Unselect points of vertex group. + */ void ED_gpencil_vgroup_deselect(struct bContext *C, struct Object *ob); /* join objects */ + +/** + * Join objects called from OBJECT_OT_join. + */ int ED_gpencil_join_objects_exec(struct bContext *C, struct wmOperator *op); /* texture coordinate utilities */ + +/** + * Convert 2d #tGPspoint to 3d #bGPDspoint. + */ void ED_gpencil_tpoint_to_point(struct ARegion *region, float origin[3], const struct tGPspoint *tpt, struct bGPDspoint *pt); +/** + * Recalculate UV for any stroke using the material. + */ void ED_gpencil_update_color_uv(struct Main *bmain, struct Material *mat); -/* extend selection to stroke intersections - * returns: +/** + * Extend selection to stroke intersections: + * \returns: * 0 - No hit * 1 - Hit in point A * 2 - Hit in point B @@ -347,17 +559,23 @@ int ED_gpencil_select_stroke_segment(struct bGPdata *gpd, void ED_gpencil_select_toggle_all(struct bContext *C, int action); void ED_gpencil_select_curve_toggle_all(struct bContext *C, int action); -/* Ensure stroke sbuffer size is enough */ +/** + * Ensure the #tGPspoint buffer (while drawing stroke) + * size is enough to save all points of the stroke. + */ struct tGPspoint *ED_gpencil_sbuffer_ensure(struct tGPspoint *buffer_array, int *buffer_size, int *buffer_used, const bool clear); void ED_gpencil_sbuffer_update_eval(struct bGPdata *gpd, struct Object *ob_eval); -/* Tag all scene grease pencil object to update. */ +/** + * Tag all scene grease pencil object to update. + */ void ED_gpencil_tag_scene_gpencil(struct Scene *scene); /* Vertex color set. */ + void ED_gpencil_fill_vertex_color_set(struct ToolSettings *ts, struct Brush *brush, struct bGPDstroke *gps); @@ -376,15 +594,30 @@ void ED_gpencil_init_random_settings(struct Brush *brush, const int mval[2], struct GpRandomSettings *random_settings); +/** + * Check if the stroke collides with brush. + */ bool ED_gpencil_stroke_check_collision(const struct GP_SpaceConversion *gsc, struct bGPDstroke *gps, const float mouse[2], const int radius, const float diff_mat[4][4]); +/** + * Check if a point is inside of the stroke. + * + * \param gps: Stroke to check. + * \param gsc: Space conversion data. + * \param mouse: Mouse position. + * \param diff_mat: View matrix. + * \return True if the point is inside. + */ bool ED_gpencil_stroke_point_is_inside(const struct bGPDstroke *gps, const struct GP_SpaceConversion *gsc, const int mouse[2], const float diff_mat[4][4]); +/** + * Get the bigger 2D bound box points. + */ void ED_gpencil_projected_2d_bound_box(const struct GP_SpaceConversion *gsc, const struct bGPDstroke *gps, const float diff_mat[4][4], @@ -400,18 +633,27 @@ struct bGPDstroke *ED_gpencil_stroke_nearest_to_ends(struct bContext *C, const float ctrl2[2], const float radius, int *r_index); +/** + * Get extremes of stroke in 2D using current view. + */ void ED_gpencil_stroke_extremes_to2d(const struct GP_SpaceConversion *gsc, const float diff_mat[4][4], struct bGPDstroke *gps, float r_ctrl1[2], float r_ctrl2[2]); +/** + * Join two stroke using a contact point index and trimming the rest. + */ struct bGPDstroke *ED_gpencil_stroke_join_and_trim(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, struct bGPDstroke *gps_dst, const int pt_index); +/** + * Close if the distance between extremes is below threshold. + */ void ED_gpencil_stroke_close_by_distance(struct bGPDstroke *gps, const float threshold); #ifdef __cplusplus |