From dfbb13b593126bd50b41c10b9671e6de0dc001fe Mon Sep 17 00:00:00 2001 From: Antonio Vazquez Date: Fri, 3 Jul 2020 13:50:27 +0200 Subject: GPencil: Cleanup more comments (cont) --- source/blender/blenkernel/intern/gpencil.c | 257 ++++++++++++++++++++++++++--- 1 file changed, 233 insertions(+), 24 deletions(-) (limited to 'source/blender/blenkernel/intern/gpencil.c') diff --git a/source/blender/blenkernel/intern/gpencil.c b/source/blender/blenkernel/intern/gpencil.c index 3a0449dd4be..6a9511d8275 100644 --- a/source/blender/blenkernel/intern/gpencil.c +++ b/source/blender/blenkernel/intern/gpencil.c @@ -925,7 +925,11 @@ void BKE_gpencil_frame_delete_laststroke(bGPDlayer *gpl, bGPDframe *gpf) /* ************************************************** */ /* GP Layer API */ -/* Check if the given layer is able to be edited or not */ +/** + * Check if the given layer is able to be edited or not. + * \param gpl: Grease pencil layer + * \return True if layer is editable + */ bool BKE_gpencil_layer_is_editable(const bGPDlayer *gpl) { /* Sanity check */ @@ -942,7 +946,12 @@ bool BKE_gpencil_layer_is_editable(const bGPDlayer *gpl) return false; } -/* Look up the gp-frame on the requested frame number, but don't add a new one */ +/** + * Look up the gp-frame on the requested frame number, but don't add a new one. + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \return Pointer to frame + */ bGPDframe *BKE_gpencil_layer_frame_find(bGPDlayer *gpl, int cframe) { bGPDframe *gpf; @@ -959,9 +968,14 @@ bGPDframe *BKE_gpencil_layer_frame_find(bGPDlayer *gpl, int cframe) return NULL; } -/* get the appropriate gp-frame from a given layer +/** Get the appropriate gp-frame from a given layer * - this sets the layer's actframe var (if allowed to) * - extension beyond range (if first gp-frame is after all frame in interest and cannot add) + * + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \param addnew: Add option + * \return Pointer to new frame */ bGPDframe *BKE_gpencil_layer_frame_get(bGPDlayer *gpl, int cframe, eGP_GetFrame_Mode addnew) { @@ -1117,7 +1131,12 @@ bGPDframe *BKE_gpencil_layer_frame_get(bGPDlayer *gpl, int cframe, eGP_GetFrame_ return gpl->actframe; } -/* delete the given frame from a layer */ +/** + * Delete the given frame from a layer. + * \param gpl: Grease pencil layer + * \param gpf: Grease pencil frame + * \return True if delete was done + */ bool BKE_gpencil_layer_frame_delete(bGPDlayer *gpl, bGPDframe *gpf) { bool changed = false; @@ -1141,6 +1160,12 @@ bool BKE_gpencil_layer_frame_delete(bGPDlayer *gpl, bGPDframe *gpf) return changed; } +/** + * Get layer by name + * \param gpd: Grease pencil data-block + * \param name: Layer name + * \return Pointer to layer + */ bGPDlayer *BKE_gpencil_layer_named_get(bGPdata *gpd, const char *name) { if (name[0] == '\0') { @@ -1149,6 +1174,12 @@ bGPDlayer *BKE_gpencil_layer_named_get(bGPdata *gpd, const char *name) return BLI_findstring(&gpd->layers, name, offsetof(bGPDlayer, info)); } +/** + * Get mask layer by name. + * \param gpl: Grease pencil layer + * \param name: Mask name + * \return Pointer to mask layer + */ bGPDlayer_Mask *BKE_gpencil_layer_mask_named_get(bGPDlayer *gpl, const char *name) { if (name[0] == '\0') { @@ -1157,6 +1188,12 @@ bGPDlayer_Mask *BKE_gpencil_layer_mask_named_get(bGPDlayer *gpl, const char *nam return BLI_findstring(&gpl->mask_layers, name, offsetof(bGPDlayer_Mask, name)); } +/** + * Add grease pencil mask layer. + * \param gpl: Grease pencil layer + * \param name: Name of the mask + * \return Pointer to new mask layer + */ bGPDlayer_Mask *BKE_gpencil_layer_mask_add(bGPDlayer *gpl, const char *name) { @@ -1168,6 +1205,11 @@ bGPDlayer_Mask *BKE_gpencil_layer_mask_add(bGPDlayer *gpl, const char *name) return mask; } +/** + * Remove grease pencil mask layer. + * \param gpl: Grease pencil layer + * \param mask: Grease pencil mask layer + */ void BKE_gpencil_layer_mask_remove(bGPDlayer *gpl, bGPDlayer_Mask *mask) { BLI_freelinkN(&gpl->mask_layers, mask); @@ -1175,6 +1217,11 @@ void BKE_gpencil_layer_mask_remove(bGPDlayer *gpl, bGPDlayer_Mask *mask) CLAMP_MIN(gpl->act_mask, 0); } +/** + * Remove any reference to mask layer. + * \param gpd: Grease pencil data-block + * \param name: Name of the mask layer + */ void BKE_gpencil_layer_mask_remove_ref(bGPdata *gpd, const char *name) { bGPDlayer_Mask *mask_next; @@ -1206,6 +1253,11 @@ static int gpencil_cb_sort_masks(const void *arg1, const void *arg2) return val; } +/** + * Sort grease pencil mask layers. + * \param gpd: Grease pencil data-block + * \param gpl: Grease pencil layer + */ void BKE_gpencil_layer_mask_sort(bGPdata *gpd, bGPDlayer *gpl) { /* Update sort index. */ @@ -1221,6 +1273,10 @@ void BKE_gpencil_layer_mask_sort(bGPdata *gpd, bGPDlayer *gpl) BLI_listbase_sort(&gpl->mask_layers, gpencil_cb_sort_masks); } +/** + * Sort all grease pencil mask layer. + * \param gpd: Grease pencil data-block + */ void BKE_gpencil_layer_mask_sort_all(bGPdata *gpd) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -1249,12 +1305,21 @@ static int gpencil_cb_cmp_frame(void *thunk, const void *a, const void *b) return 0; } +/** + * Sort grease pencil frames. + * \param gpl: Grease pencil layer + * \param r_has_duplicate_frames: Duplicated frames flag + */ void BKE_gpencil_layer_frames_sort(struct bGPDlayer *gpl, bool *r_has_duplicate_frames) { BLI_listbase_sort_r(&gpl->frames, gpencil_cb_cmp_frame, r_has_duplicate_frames); } -/* get the active gp-layer for editing */ +/** + * Get the active grease pencil layer for editing. + * \param gpd: Grease pencil data-block + * \return Pointer to layer + */ bGPDlayer *BKE_gpencil_layer_active_get(bGPdata *gpd) { /* error checking */ @@ -1273,7 +1338,11 @@ bGPDlayer *BKE_gpencil_layer_active_get(bGPdata *gpd) return NULL; } -/* set the active gp-layer */ +/** + * Set active grease pencil layer. + * \param gpd: Grease pencil data-block + * \param active: Grease pencil layer to set as active + */ void BKE_gpencil_layer_active_set(bGPdata *gpd, bGPDlayer *active) { /* error checking */ @@ -1296,7 +1365,11 @@ void BKE_gpencil_layer_active_set(bGPdata *gpd, bGPDlayer *active) } } -/* Set locked layers for autolock mode. */ +/** + * Set locked layers for autolock mode. + * \param gpd: Grease pencil data-block + * \param unlock: Unlock flag + */ void BKE_gpencil_layer_autolock_set(bGPdata *gpd, const bool unlock) { BLI_assert(gpd != NULL); @@ -1327,7 +1400,11 @@ void BKE_gpencil_layer_autolock_set(bGPdata *gpd, const bool unlock) } } -/* delete the active gp-layer */ +/** + * Delete grease pencil layer. + * \param gpd: Grease pencil data-block + * \param gpl: Grease pencil layer + */ void BKE_gpencil_layer_delete(bGPdata *gpd, bGPDlayer *gpl) { /* error checking */ @@ -1350,6 +1427,11 @@ void BKE_gpencil_layer_delete(bGPdata *gpd, bGPDlayer *gpl) BLI_freelinkN(&gpd->layers, gpl); } +/** + * Get grease pencil material from brush. + * \param brush: Brush + * \return Pointer to material + */ Material *BKE_gpencil_brush_material_get(Brush *brush) { Material *ma = NULL; @@ -1362,6 +1444,11 @@ Material *BKE_gpencil_brush_material_get(Brush *brush) return ma; } +/** + * Set grease pencil brush material. + * \param brush: Brush + * \param ma: Material + */ void BKE_gpencil_brush_material_set(Brush *brush, Material *ma) { BLI_assert(brush); @@ -1377,7 +1464,13 @@ void BKE_gpencil_brush_material_set(Brush *brush, Material *ma) } } -/* Adds the pinned material to the object if necessary. */ +/** + * Adds the pinned material to the object if necessary. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param brush: Brush + * \return Pointer to material + */ Material *BKE_gpencil_object_material_ensure_from_brush(Main *bmain, Object *ob, Brush *brush) { if (brush->gpencil_settings->flag & GP_BRUSH_MATERIAL_PINNED) { @@ -1397,7 +1490,13 @@ Material *BKE_gpencil_object_material_ensure_from_brush(Main *bmain, Object *ob, } } -/* Assigns the material to object (if not already present) and returns its index (mat_nr). */ +/** + * Assigns the material to object (if not already present) and returns its index (mat_nr). + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param material: Material + * \return Index of the material + */ int BKE_gpencil_object_material_ensure(Main *bmain, Object *ob, Material *material) { if (!material) { @@ -1414,8 +1513,11 @@ int BKE_gpencil_object_material_ensure(Main *bmain, Object *ob, Material *materi /** * Creates a new gpencil material and assigns it to object. - * - * \param *r_index: value is set to zero based index of the new material if \a r_index is not NULL. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param name: Material name + * \param r_index: value is set to zero based index of the new material if \a r_index is not NULL. + * \return Materil pointer */ Material *BKE_gpencil_object_material_new(Main *bmain, Object *ob, const char *name, int *r_index) { @@ -1431,7 +1533,12 @@ Material *BKE_gpencil_object_material_new(Main *bmain, Object *ob, const char *n return ma; } -/* Returns the material for a brush with respect to its pinned state. */ +/** + * Returns the material for a brush with respect to its pinned state. + * \param ob: Grease pencil object + * \param brush: Brush + * \return Material pointer + */ Material *BKE_gpencil_object_material_from_brush_get(Object *ob, Brush *brush) { if ((brush) && (brush->gpencil_settings) && @@ -1444,7 +1551,12 @@ Material *BKE_gpencil_object_material_from_brush_get(Object *ob, Brush *brush) } } -/* Returns the material index for a brush with respect to its pinned state. */ +/** + * Returns the material index for a brush with respect to its pinned state. + * \param ob: Grease pencil object + * \param brush: Brush + * \return Materil index + */ int BKE_gpencil_object_material_get_index_from_brush(Object *ob, Brush *brush) { if ((brush) && (brush->gpencil_settings->flag & GP_BRUSH_MATERIAL_PINNED)) { @@ -1455,7 +1567,13 @@ int BKE_gpencil_object_material_get_index_from_brush(Object *ob, Brush *brush) } } -/* Guaranteed to return a material assigned to object. Returns never NULL. */ +/** + * Guaranteed to return a material assigned to object. Returns never NULL. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param ts: Toolsettings + * \return Material pointer + */ Material *BKE_gpencil_object_material_ensure_from_active_input_toolsettings(Main *bmain, Object *ob, ToolSettings *ts) @@ -1469,7 +1587,13 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_toolsettings(Main } } -/* Guaranteed to return a material assigned to object. Returns never NULL. */ +/** + * Guaranteed to return a material assigned to object. Returns never NULL. + * \param bmain: Main pointer + * \param ob: Grease pencil obejct + * \param brush: Brush + * \return Material pointer + */ Material *BKE_gpencil_object_material_ensure_from_active_input_brush(Main *bmain, Object *ob, Brush *brush) @@ -1490,6 +1614,8 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_brush(Main *bmain /** * Guaranteed to return a material assigned to object. Returns never NULL. * Only use this for materials unrelated to user input. + * \param ob: Grease pencil object + * \return Material pointer */ Material *BKE_gpencil_object_material_ensure_from_active_input_material(Object *ob) { @@ -1501,7 +1627,11 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_material(Object * return BKE_material_default_gpencil(); } -/* Get active color, and add all default settings if we don't find anything */ +/** + * Get active color, and add all default settings if we don't find anything. + * \param ob: Grease pencil object + * \return Material pointer + */ Material *BKE_gpencil_object_material_ensure_active(Object *ob) { Material *ma = NULL; @@ -1520,6 +1650,11 @@ Material *BKE_gpencil_object_material_ensure_active(Object *ob) } /* ************************************************** */ +/** + * Check if stroke has any point selected + * \param gps: Grease pencil stroke + * \return True if selected + */ bool BKE_gpencil_stroke_select_check(const bGPDstroke *gps) { const bGPDspoint *pt; @@ -1535,7 +1670,11 @@ bool BKE_gpencil_stroke_select_check(const bGPDstroke *gps) /* ************************************************** */ /* GP Object - Vertex Groups */ -/* remove a vertex group */ +/** + * Remove a vertex group. + * \param ob: Grease pencil object + * \param defgroup: deform group + */ void BKE_gpencil_vgroup_remove(Object *ob, bDeformGroup *defgroup) { bGPdata *gpd = ob->data; @@ -1574,6 +1713,10 @@ void BKE_gpencil_vgroup_remove(Object *ob, bDeformGroup *defgroup) DEG_id_tag_update(&gpd->id, ID_RECALC_TRANSFORM | ID_RECALC_GEOMETRY); } +/** + * Ensure stroke has vertex group. + * \param gps: Grease pencil stroke + */ void BKE_gpencil_dvert_ensure(bGPDstroke *gps) { if (gps->dvert == NULL) { @@ -1646,7 +1789,12 @@ float BKE_gpencil_multiframe_falloff_calc( return value; } -/* reassign strokes using a material */ +/** + * Reassign strokes using a material. + * \param gpd: Grease pencil data-block + * \param totcol: Total materials + * \param index: Index of the material + */ void BKE_gpencil_material_index_reassign(bGPdata *gpd, int totcol, int index) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -1662,7 +1810,12 @@ void BKE_gpencil_material_index_reassign(bGPdata *gpd, int totcol, int index) } } -/* remove strokes using a material */ +/** + * Remove strokes using a material. + * \param gpd: Grease pencil data-block + * \param index: Index of the material + * \return True if removed + */ bool BKE_gpencil_material_index_used(bGPdata *gpd, int index) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -1678,6 +1831,12 @@ bool BKE_gpencil_material_index_used(bGPdata *gpd, int index) return false; } +/** + * Remap material + * \param gpd: Grease pencil data-block + * \param remap: Remap index + * \param remap_len: Remap length + */ void BKE_gpencil_material_remap(struct bGPdata *gpd, const unsigned int *remap, unsigned int remap_len) @@ -1703,7 +1862,15 @@ void BKE_gpencil_material_remap(struct bGPdata *gpd, #undef MAT_NR_REMAP } -/* Load a table with material conversion index for merged materials. */ +/** + * Load a table with material conversion index for merged materials. + * \param ob: Grease pencil object + * \param hue_threshold: Threshold for Hue + * \param sat_threshold: Threshold for Saturation + * \param val_threshold: Threshold for Value + * \param r_mat_table : return material table + * \return True if done + */ bool BKE_gpencil_merge_materials_table_get(Object *ob, const float hue_threshold, const float sat_threshold, @@ -1799,7 +1966,10 @@ bool BKE_gpencil_merge_materials_table_get(Object *ob, return changed; } -/* statistics functions */ +/** + * Calc grease pencil statistics functions. + * \param gpd: Grease pencil data-block + */ void BKE_gpencil_stats_update(bGPdata *gpd) { gpd->totlayer = 0; @@ -1819,7 +1989,12 @@ void BKE_gpencil_stats_update(bGPdata *gpd) } } -/* get material index (0-based like mat_nr not actcol) */ +/** + * Get material index (0-based like mat_nr not actcol). + * \param ob: Grease pencil object + * \param ma: Material + * \return Index of the material + */ int BKE_gpencil_object_material_index_get(Object *ob, Material *ma) { short *totcol = BKE_object_material_len_p(ob); @@ -1834,7 +2009,11 @@ int BKE_gpencil_object_material_index_get(Object *ob, Material *ma) return -1; } -/* Create a default palette */ +/** + * Create a default palette. + * \param bmain: Main pointer + * \param scene: Scene + */ void BKE_gpencil_palette_ensure(Main *bmain, Scene *scene) { const int totcol = 120; @@ -1884,6 +2063,14 @@ void BKE_gpencil_palette_ensure(Main *bmain, Scene *scene) } } +/** + * Create grease pencil strokes from image + * \param sima: Image + * \param gpf: Grease pencil frame + * \param size: Size + * \param mask: Mask + * \return True if done + */ bool BKE_gpencil_from_image(SpaceImage *sima, bGPDframe *gpf, const float size, const bool mask) { Image *image = sima->image; @@ -2141,6 +2328,11 @@ void BKE_gpencil_visible_stroke_iter(ViewLayer *view_layer, } } +/** + * Update original pointers in evaluated frame. + * \param gpf_orig: Original greas epencil frame + * \param gpf_eval: Evaluated grease pencil frame + */ void BKE_gpencil_frame_original_pointers_update(const struct bGPDframe *gpf_orig, const struct bGPDframe *gpf_eval) { @@ -2169,6 +2361,11 @@ void BKE_gpencil_frame_original_pointers_update(const struct bGPDframe *gpf_orig } } +/** + * Update pointers of eval data to original data to keep references. + * \param ob_orig: Original grease pencil object + * \param ob_eval: Evaluated grease pencil object + */ void BKE_gpencil_update_orig_pointers(const Object *ob_orig, const Object *ob_eval) { bGPdata *gpd_eval = (bGPdata *)ob_eval->data; @@ -2199,6 +2396,13 @@ void BKE_gpencil_update_orig_pointers(const Object *ob_orig, const Object *ob_ev } } +/** + * Get parent matrix, including layer parenting. + * \param depsgraph: Depsgraph + * \param obact: Grease pencil object + * \param gpl: Grease pencil layer + * \param diff_mat: Result parent matrix + */ void BKE_gpencil_parent_matrix_get(const Depsgraph *depsgraph, Object *obact, bGPDlayer *gpl, @@ -2248,6 +2452,11 @@ void BKE_gpencil_parent_matrix_get(const Depsgraph *depsgraph, } } +/** + * Update parent matrix. + * \param depsgraph: Depsgraph + * \param ob: Grease pencil object + */ void BKE_gpencil_update_layer_parent(const Depsgraph *depsgraph, Object *ob) { if (ob->type != OB_GPENCIL) { -- cgit v1.2.3