diff options
author | Campbell Barton <ideasman42@gmail.com> | 2019-01-23 08:24:37 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2019-01-23 08:24:37 +0300 |
commit | 4f2bc2f0e59964a3f4ef32aca7b8e15c53940085 (patch) | |
tree | 3e1c5d1e74cab6d6ea28d857d8ccac3b6e7a8a64 | |
parent | 6dfe6b4f196d20be24a0c71dcc90ed5569f9b565 (diff) |
Cleanup: use doxy comments for gizmo structs
Also move comments before members (better for clang-format).
-rw-r--r-- | source/blender/windowmanager/gizmo/WM_gizmo_types.h | 142 |
1 files changed, 76 insertions, 66 deletions
diff --git a/source/blender/windowmanager/gizmo/WM_gizmo_types.h b/source/blender/windowmanager/gizmo/WM_gizmo_types.h index ee574d26750..b000305d15b 100644 --- a/source/blender/windowmanager/gizmo/WM_gizmo_types.h +++ b/source/blender/windowmanager/gizmo/WM_gizmo_types.h @@ -56,8 +56,10 @@ struct wmKeyConfig; * #wmGizmo.state */ typedef enum eWM_GizmoFlagState { - WM_GIZMO_STATE_HIGHLIGHT = (1 << 0), /* while hovered */ - WM_GIZMO_STATE_MODAL = (1 << 1), /* while dragging */ + /** While hovered. */ + WM_GIZMO_STATE_HIGHLIGHT = (1 << 0), + /** While dragging. */ + WM_GIZMO_STATE_MODAL = (1 << 1), WM_GIZMO_STATE_SELECT = (1 << 2), } eWM_GizmoFlagState; @@ -67,9 +69,12 @@ typedef enum eWM_GizmoFlagState { * Flags for individual gizmos. */ typedef enum eWM_GizmoFlag { - WM_GIZMO_DRAW_HOVER = (1 << 0), /* draw *only* while hovering */ - WM_GIZMO_DRAW_MODAL = (1 << 1), /* draw while dragging */ - WM_GIZMO_DRAW_VALUE = (1 << 2), /* draw an indicator for the current value while dragging */ + /** Draw *only* while hovering. */ + WM_GIZMO_DRAW_HOVER = (1 << 0), + /** Draw while dragging. */ + WM_GIZMO_DRAW_MODAL = (1 << 1), + /** Draw an indicator for the current value while dragging. */ + WM_GIZMO_DRAW_VALUE = (1 << 2), WM_GIZMO_HIDDEN = (1 << 3), WM_GIZMO_HIDDEN_SELECT = (1 << 4), /** @@ -104,7 +109,7 @@ typedef enum eWM_GizmoFlagGroupTypeFlag { WM_GIZMOGROUPTYPE_SCALE = (1 << 1), /** Gizmos can be depth culled with scene objects (covered by other geometry - TODO) */ WM_GIZMOGROUPTYPE_DEPTH_3D = (1 << 2), - /** Gizmos can be selected */ + /** Gizmos can be selected. */ WM_GIZMOGROUPTYPE_SELECT = (1 << 3), /** The gizmo group is to be kept (not removed on loading a new file for eg). */ WM_GIZMOGROUPTYPE_PERSISTENT = (1 << 4), @@ -119,7 +124,7 @@ typedef enum eWM_GizmoFlagGroupTypeFlag { * The main issue is controlling how a gizmo is activated with a tool * when a tool can activate multiple operators based on the key-map. * We could even move the options into the key-map item. - * ~ campbell */ + * ~ campbell. */ WM_GIZMOGROUPTYPE_TOOL_INIT = (1 << 6), } eWM_GizmoFlagGroupTypeFlag; @@ -128,7 +133,7 @@ typedef enum eWM_GizmoFlagGroupTypeFlag { * #wmGizmoGroup.init_flag */ typedef enum eWM_GizmoFlagGroupInitFlag { - /* mgroup has been initialized */ + /** Gizmo-group has been initialized. */ WM_GIZMOGROUP_INIT_SETUP = (1 << 0), WM_GIZMOGROUP_INIT_REFRESH = (1 << 1), } eWM_GizmoFlagGroupInitFlag; @@ -138,11 +143,11 @@ typedef enum eWM_GizmoFlagGroupInitFlag { * Gizmo-map type update flag */ typedef enum eWM_GizmoFlagMapTypeUpdateFlag { - /* A new type has been added, needs to be initialized for all views. */ + /** A new type has been added, needs to be initialized for all views. */ WM_GIZMOMAPTYPE_UPDATE_INIT = (1 << 0), WM_GIZMOMAPTYPE_UPDATE_REMOVE = (1 << 1), - /* Needed because keymap may be registered before and after window initialization. + /** Needed because keymap may be registered before and after window initialization. * So we need to keep track of keymap initialization separately. */ WM_GIZMOMAPTYPE_KEYMAP_INIT = (1 << 2), } eWM_GizmoFlagMapTypeUpdateFlag; @@ -167,8 +172,8 @@ typedef enum { typedef struct wmGizmoOpElem { struct wmOperatorType *type; - /* operator properties if gizmo spawns and controls an operator, - * or owner pointer if gizmo spawns and controls a property */ + /** Operator properties if gizmo spawns and controls an operator, + * or owner pointer if gizmo spawns and controls a property. */ PointerRNA ptr; bool is_redo; @@ -178,33 +183,34 @@ typedef struct wmGizmoOpElem { struct wmGizmo { struct wmGizmo *next, *prev; - /* While we don't have a real type, use this to put type-like vars. */ + /** While we don't have a real type, use this to put type-like vars. */ const struct wmGizmoType *type; - /* Overrides 'type->modal' when set. + /** Overrides 'type->modal' when set. * Note that this is a workaround, remove if we can. */ wmGizmoFnModal custom_modal; - /* pointer back to group this gizmo is in (just for quick access) */ + /** Pointer back to group this gizmo is in (just for quick access). */ struct wmGizmoGroup *parent_gzgroup; void *py_instance; - /* rna pointer to access properties */ + /** Rna pointer to access properties. */ struct PointerRNA *ptr; - /* flags that influence the behavior or how the gizmos are drawn */ + /** Flags that influence the behavior or how the gizmos are drawn. */ eWM_GizmoFlag flag; - /* state flags (active, highlighted, selected) */ + /** State flags (active, highlighted, selected) */ eWM_GizmoFlagState state; - /* Optional ID for highlighting different parts of this gizmo. + /** Optional ID for highlighting different parts of this gizmo. * -1 when unset, otherwise a valid index. (Used as index to 'op_data'). */ int highlight_part; - /* For single click button gizmos, use a different part as a fallback, -1 when unused. */ + /** For single click button gizmos, use a different part as a fallback, -1 when unused. */ int drag_part; - /* Transformation of the gizmo in 2d or 3d space. + /** + * Transformation of the gizmo in 2d or 3d space. * - Matrix axis are expected to be unit length (scale is applied after). * - Behavior when axis aren't orthogonal depends on each gizmo. * - Typically the +Z is the primary axis for gizmos to use. @@ -213,32 +219,32 @@ struct wmGizmo { * rotation components are used for drawing and interaction. */ - /* The space this gizmo is being modified in. */ + /** The space this gizmo is being modified in. */ float matrix_space[4][4]; - /* Transformation of this gizmo. */ + /** Transformation of this gizmo. */ float matrix_basis[4][4]; - /* custom offset from origin */ + /** Custom offset from origin. */ float matrix_offset[4][4]; - /* runtime property, set the scale while drawing on the viewport */ + /** Runtime property, set the scale while drawing on the viewport. */ float scale_final; - /* user defined scale, in addition to the original one */ + /** User defined scale, in addition to the original one. */ float scale_basis; - /* user defined width for line drawing */ + /** User defined width for line drawing. */ float line_width; - /* gizmo colors (uses default fallbacks if not defined) */ + /** Gizmo colors (uses default fallbacks if not defined). */ float color[4], color_hi[4]; - /* data used during interaction */ + /** Data used during interaction. */ void *interaction_data; - /* Operator to spawn when activating the gizmo (overrides property editing), + /** Operator to spawn when activating the gizmo (overrides property editing), * an array of items (aligned with #wmGizmo.highlight_part). */ wmGizmoOpElem *op_data; int op_data_len; struct IDProperty *properties; - /* Temporary data (assume dirty). */ + /** Temporary data (assume dirty). */ union { float f; } temp; @@ -246,7 +252,7 @@ struct wmGizmo { /* over alloc target_properties after 'wmGizmoType.struct_size' */ }; -/* Similar to PropertyElemRNA, but has an identifier. */ +/** Similar to #PropertyElemRNA, but has an identifier. */ typedef struct wmGizmoProperty { const struct wmGizmoPropertyType *type; @@ -267,14 +273,14 @@ typedef struct wmGizmoProperty { typedef struct wmGizmoPropertyType { struct wmGizmoPropertyType *next, *prev; - /* PropertyType, typically 'PROP_FLOAT' */ + /** #PropertyType, typically #PROP_FLOAT. */ int data_type; int array_length; /* index within 'wmGizmoType' */ int index_in_type; - /* over alloc */ + /** over alloc. */ char idname[0]; } wmGizmoPropertyType; @@ -295,30 +301,30 @@ typedef struct wmGizmoType { const char *idname; /* MAX_NAME */ - /* Set to 'sizeof(wmGizmo)' or larger for instances of this type, + /** Set to 'sizeof(wmGizmo)' or larger for instances of this type, * use so we can cant to other types without the hassle of a custom-data pointer. */ uint struct_size; - /* Initialize struct (calloc'd 'struct_size' region). */ + /** Initialize struct (calloc'd 'struct_size' region). */ wmGizmoFnSetup setup; - /* draw gizmo */ + /** Draw gizmo. */ wmGizmoFnDraw draw; - /* determines 3d intersection by rendering the gizmo in a selection routine. */ + /** Determines 3d intersection by rendering the gizmo in a selection routine. */ wmGizmoFnDrawSelect draw_select; - /* Determine if the mouse intersects with the gizmo. + /** Determine if the mouse intersects with the gizmo. * The calculation should be done in the callback itself, -1 for no seleciton. */ wmGizmoFnTestSelect test_select; - /* handler used by the gizmo. Usually handles interaction tied to a gizmo type */ + /** Handler used by the gizmo. Usually handles interaction tied to a gizmo type. */ wmGizmoFnModal modal; - /* gizmo-specific handler to update gizmo attributes based on the property value */ + /** Gizmo-specific handler to update gizmo attributes based on the property value. */ wmGizmoFnPropertyUpdate property_update; - /* Returns the final transformation which may be different from the 'matrix', + /** Returns the final transformation which may be different from the 'matrix', * depending on the gizmo. * Notes: * - Scale isn't applied (wmGizmo.scale/user_scale). @@ -326,24 +332,24 @@ typedef struct wmGizmoType { */ wmGizmoFnMatrixBasisGet matrix_basis_get; - /* activate a gizmo state when the user clicks on it */ + /** Activate a gizmo state when the user clicks on it. */ wmGizmoFnInvoke invoke; - /* called when gizmo tweaking is done - used to free data and reset property when cancelling */ + /** Called when gizmo tweaking is done - used to free data and reset property when cancelling. */ wmGizmoFnExit exit; wmGizmoFnCursorGet cursor_get; - /* called when gizmo selection state changes */ + /** Called when gizmo selection state changes. */ wmGizmoFnSelectRefresh select_refresh; - /* Free data (not the gizmo it's self), use when the gizmo allocates it's own members. */ + /** Free data (not the gizmo it's self), use when the gizmo allocates it's own members. */ wmGizmoFnFree free; - /* RNA for properties */ + /** RNA for properties. */ struct StructRNA *srna; - /* RNA integration */ + /** RNA integration. */ ExtensionRNA ext; ListBase target_property_defs; @@ -355,7 +361,7 @@ typedef struct wmGizmoType { /* -------------------------------------------------------------------- */ /* wmGizmoGroup */ -/* factory class for a gizmo-group type, gets called every time a new area is spawned */ +/** Factory class for a gizmo-group type, gets called every time a new area is spawned. */ typedef struct wmGizmoGroupTypeRef { struct wmGizmoGroupTypeRef *next, *prev; struct wmGizmoGroupType *type; @@ -364,49 +370,50 @@ typedef struct wmGizmoGroupTypeRef { /* factory class for a gizmo-group type, gets called every time a new area is spawned */ typedef struct wmGizmoGroupType { const char *idname; /* MAX_NAME */ - const char *name; /* gizmo-group name - displayed in UI (keymap editor) */ + /** Gizmo-group name - displayed in UI (keymap editor). */ + const char *name; char owner_id[64]; /* MAX_NAME */ - /* poll if gizmo-map should be visible */ + /** Poll if gizmo-map should be visible. */ wmGizmoGroupFnPoll poll; - /* initially create gizmos and set permanent data - stuff you only need to do once */ + /** Initially create gizmos and set permanent data - stuff you only need to do once. */ wmGizmoGroupFnInit setup; - /* refresh data, only called if recreate flag is set (WM_gizmomap_tag_refresh) */ + /** Refresh data, only called if recreate flag is set (WM_gizmomap_tag_refresh). */ wmGizmoGroupFnRefresh refresh; - /* refresh data for drawing, called before each redraw */ + /** Refresh data for drawing, called before each redraw. */ wmGizmoGroupFnDrawPrepare draw_prepare; - /* Initialize data for before invoke. */ + /** Initialize data for before invoke. */ wmGizmoGroupFnInvokePrepare invoke_prepare; - /* Keymap init callback for this gizmo-group (optional), + /** Keymap init callback for this gizmo-group (optional), * will fall back to default tweak keymap when left NULL. */ wmGizmoGroupFnSetupKeymap setup_keymap; - /* Optionally subscribe to wmMsgBus events, + /** Optionally subscribe to wmMsgBus events, * these are calculated automatically from RNA properties, * only needed if gizmos depend indirectly on properties. */ wmGizmoGroupFnMsgBusSubscribe message_subscribe; - /* keymap created with callback from above */ + /** Keymap created with callback from above. */ struct wmKeyMap *keymap; - /* Only for convenient removal. */ + /** Only for convenient removal. */ struct wmKeyConfig *keyconf; /* Note: currently gizmo-group instances don't store properties, * they're kept in the tool properties. */ - /* RNA for properties */ + /** RNA for properties. */ struct StructRNA *srna; - /* RNA integration */ + /** RNA integration. */ ExtensionRNA ext; eWM_GizmoFlagGroupTypeFlag flag; - /* So we know which group type to update. */ + /** So we know which group type to update. */ eWM_GizmoFlagMapTypeUpdateFlag type_update_flag; - /* same as gizmo-maps, so registering/unregistering goes to the correct region */ + /** Same as gizmo-maps, so registering/unregistering goes to the correct region. */ struct wmGizmoMapType_Params gzmap_params; } wmGizmoGroupType; @@ -419,11 +426,14 @@ typedef struct wmGizmoGroup { struct wmGizmoMap *parent_gzmap; - void *py_instance; /* python stores the class instance here */ - struct ReportList *reports; /* errors and warnings storage */ + /** Python stores the class instance here. */ + void *py_instance; + /** Errors and warnings storage. */ + struct ReportList *reports; void *customdata; - void (*customdata_free)(void *); /* for freeing customdata from above */ + /** For freeing customdata from above. */ + void (*customdata_free)(void *); eWM_GizmoFlagGroupInitFlag init_flag; } wmGizmoGroup; |