[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [58821] branches/soc-2012-sushi/source/ blender/blenkernel/intern/snap.c: brought accross a lot of the comments from the wiki for snap.c
luke frisken
l.frisken at gmail.com
Fri Aug 2 08:46:53 CEST 2013
Revision: 58821
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=58821
Author: lfrisken
Date: 2013-08-02 06:46:53 +0000 (Fri, 02 Aug 2013)
Log Message:
-----------
brought accross a lot of the comments from the wiki for snap.c
Modified Paths:
--------------
branches/soc-2012-sushi/source/blender/blenkernel/intern/snap.c
Modified: branches/soc-2012-sushi/source/blender/blenkernel/intern/snap.c
===================================================================
--- branches/soc-2012-sushi/source/blender/blenkernel/intern/snap.c 2013-08-02 06:10:53 UTC (rev 58820)
+++ branches/soc-2012-sushi/source/blender/blenkernel/intern/snap.c 2013-08-02 06:46:53 UTC (rev 58821)
@@ -103,12 +103,23 @@
SnapPoint isect_point; //for use if the intersection is a single point (isect_type == SNAP_ISECT_TYPE_POINT)
};
+/*Snap struct/class is used for calculating snaps, and drawing them.
+ *It can be thought of as an abstract class. It doesn't do anything by itself,
+ *but it has many subclasses which do*/
struct Snap{
+ /*s_type is the type of snap (Mesh, Curve, Bone, Axis...)*/
Snap_type s_type;
- int snap_found; //boolean whether snap point has been found
+ /*snap found is boolean whether snap point has been found*/
+ int snap_found;
+ /*snap_point is the storage point for the calculated snap point*/
SnapPoint snap_point;
- SnapPoint* closest_point; //previously calculated closest point to mouse and screen.
- Snap* pick; //previously calculated snap to use as a picking point in modes such as parallel snap and planar snap
+ /*closest_point, when set is used during calculations to ignore
+ *potential snaps which are not as close to the screen (depth) or the mouse.
+ *It is the previously calculated closest point to mouse and screen.*/
+ SnapPoint* closest_point;
+ /*pick is a previously calculated snap to be used for mosed such as planar
+ *and parallel snapping, as the user picked face/line/vert.*/
+ Snap* pick;
//TODO: all extra data in Snap should be subject to streamlining and change
//in the near future, as soon as I get something working. A lot of quick
@@ -127,25 +138,29 @@
/*internal calculation data*/
float ray_start[3], ray_normal[3];
float ray_start_local[3], ray_normal_local[3];
+ /*min_distance is the minimum distance from the mouse to the snap point required
+ *for the snap point to be valid during calculations*/
int min_distance;
- //matrix storage
+ /*matrix storage*/
float imat[4][4];
float timat[3][3];
-
//snap type -- type of snap to calculate
//geom_data_type
//transform
- /*subclass data struct*/
+ /*snap_data stores the data for Snap's subclasses (e.g. SnapMesh_data)*/
void* snap_data;
/*function pointers*/
+ /*run is the function which calculates the snap.*/
void (*run)(Snap*);
SnapIsect* (*interesect)(Snap*,Snap*); //for use with multisnap
+ /*draws the snap. By default this is set to Snap_draw_default()*/
void (*draw)(Snap*);
+ /*function pointer to the subclass's free function*/
void (*free)(Snap*);
//void callback for doing transform -- function pointer
};
@@ -163,8 +178,10 @@
/*events and state machine variables*/
/*most are hacks to get this working for now*/
SnapSystem_state state;
- Snap* pick; //used for parallel snap, perpendicular and planar snap to store user picked geometry
+ /*used for parallel snap, perpendicular and planar snap to store user picked geometry*/
+ Snap* pick;
+
/*external data pointers required by all snap modes*/
bContext* C;
Scene* scene;
@@ -172,9 +189,12 @@
ARegion* ar;
Object* obedit;
- SnapPoint snap_point; //storage of the snapsystem's current snap point for access by the outside world
- int min_distance; //minimum distance between mouse and geometry for snap to occur
- int retval; //if a snap_point has been found retval == 1 else retval == 0
+ /*snap_point is storage of the snapsystem's current snap point for access by the outside world*/
+ SnapPoint snap_point;
+ /*minimum distance between mouse and geometry for snap to occur*/
+ int min_distance;
+ /* reval is a boolean indicating whether or not a valid snap point has been found*/
+ int retval;
//list of objects in the scene which the snapssystem can currently operate upon
ListBase ob_list;
@@ -182,10 +202,21 @@
SnapSystem_mode_select mode_select; //todo: find out more about what this does
- void* callback_data; //data from external system (e.g. transform) for use in callbacks
- void (*update_callback)(SnapSystem *ssystem, void* callback_data, SnapPoint sp); //update the view in external system, but don't finalize the snap.
+ /*callback_data is the data assigned from parent code using snapsystem (e.g. transform)
+ *to be used when the function pointers update, finish or cancel_callback are called.*/
+ void* callback_data;
+
+ /*update_callback gets called when the snapping system has not yet recieved confirmation from
+ *the user of the chosen snap point, but there is a temporary snap_point available for providing
+ *realtime feedback to the user of their actions when moving the mouse. In the case of transform,
+ *this means the geometry moves towards the snap point without permenantly being applied.*/
+ void (*update_callback)(SnapSystem *ssystem, void* callback_data, SnapPoint sp);
+
void (*nofeedback_callback)(SnapSystem *ssytem, void* callback_data); //TODO: change name of this function
- void (*finish_callback)(SnapSystem *ssystem, void* callback_data, SnapPoint sp); //update the view and finalize the snap.
+ /*finish_callback is the same as update_callback, but the snap_point is to be applied this time.*/
+ void (*finish_callback)(SnapSystem *ssystem, void* callback_data, SnapPoint sp);
+ /*cancel_callback tells the code using the snapsystem that the current snapsystem snap
+ *search has been cancelled.*/
void (*cancel_callback)(SnapSystem *ssystem, void* callback_data);
void (*object_iterator)(SnapSystem* ssystem, void* callback_data);
@@ -195,6 +226,8 @@
void (*bonedata_selector)(SnapStack* stack, void* callback_data);
};
+/*SnapSystem_create is a function used to setup and create an instance of SnapSystem.
+ *Remember to call SnapSystem_free() when finished with it.*/
SnapSystem* SnapSystem_create( Scene* scene, View3D* v3d, ARegion* ar, Object* obedit, bContext* C,
void* callback_data,
void (*update_callback)(SnapSystem *ssystem, void* callback_data, SnapPoint sp),
@@ -366,6 +399,8 @@
ssystem->retval |= retval;
}
+/*evaluate the SnapStack contained within SnapSystem to
+ *allow final snappoint to be aquired and for draw functions to work. */
void SnapSystem_evaluate_stack(SnapSystem* ssystem){
ssystem->object_iterator(ssystem, NULL);
SnapSystem_state_logic(ssystem);
@@ -562,6 +597,9 @@
//}
+
+/*This function drives the snapping system by passing it events. It indicates whether the events
+ * have been consumed by its return value, so external code can act accordingly.*/
/*TODO:
there will be a patch soon to replace this with function based state handling, according to Martin's Idea.
I've experimented with it a bit so far on a small scale and it makes sense, just ran out of time for this patch
@@ -663,6 +701,8 @@
ssystem->n_obs = 0;
}
+/*SnapSystem operates on a specific list of objects. This function is used to add objects to that list.
+ *There are other internal functions which use this function to add objects automatically by a filter.*/
void SnapSystem_add_ob(SnapSystem* ssystem, Object* ob){
SnapObRef *ob_ref = MEM_callocN(sizeof(TransSnapPoint), "SnapObRef");
ob_ref->ob = ob;
@@ -677,6 +717,7 @@
return ob_ref->ob;
}
+/*calls draw for each of the active snaps in the stack*/
void SnapSystem_draw(SnapSystem* ssystem){
Snap* s;
if(ssystem->retval && SnapStack_getN_Snaps(ssystem->sstack) > 0){
@@ -713,6 +754,7 @@
}
}
+/*reset snap system back to default state*/
void SnapSystem_reset(SnapSystem* ssystem){
SnapSystem_reset_ob_list(ssystem);
SnapSystem_reset_snappoint(ssystem);
@@ -785,11 +827,16 @@
/* -- Snap Class -- */
+/*This class represents an individual snap. */
+
+/*This function creates an instance of the Snap class.
+ *Don't forget to call Snap_free on it when you're finished with it!*/
Snap* Snap_create(Snap_type s_type,
Scene *scene, Object* ob, View3D *v3d, ARegion *ar, bContext *C, int mval[2],
void (*run)(Snap*), void (*draw)(Snap*), void (*free)(Snap*)){
Snap* s = (Snap*)MEM_mallocN(sizeof(Snap), "snap");
+ /*s_type is the type of snap (Mesh, Curve, Bone, Axis...)*/
s->s_type = s_type;
s->scene = scene;
@@ -799,16 +846,27 @@
s->C = C;
copy_v2_v2_int(s->mval, mval);
+ /*min_distance is the minimum distance from the mouse to the snap point required
+ *for the snap point to be valid during calculations*/
s->min_distance = 30; //TODO: change to a user defined value;
-
+ /*pick is a previously calculated snap to be used for mosed such as planar and
+ *parallel snapping, as the user picked face/line/vert. */
s->pick = NULL;
+ /*closes_point is a pointer, that when set is used during calculations to ignore
+ *potential snaps which are not as close to the screen (depth) or the mouse.*/
s->closest_point = NULL;
s->snap_found = 0;
//TODO: pass the function pointers in as arguments
s->run = run;
s->draw = draw;
+
+ /*This variable stores the function pointer to the subclass's free function.
+ *It's an internal variable, please call Snap_free instead if you want to free
+ * the Snap class*/
s->free = free;
+
+ /*snap_data stores the data for Snap's subclasses (e.g. SnapMesh_data)*/
s->snap_data = NULL;
return s;
}
@@ -869,6 +927,9 @@
s->free(s);
}
+/*Snap_free_f() frees Snap struct's internal data. This is useful to call
+ *after Snap's subclasses have finished their own free, and need to free
+ *parent data. */
void Snap_free_f(Snap* s){
MEM_freeN(s);
}
@@ -881,6 +942,8 @@
s->draw(s);
}
+/*Default drawing function to be assigned to s->draw.
+ *It draws the snap_point as a circle at its location.*/
void Snap_draw_default(Snap *UNUSED(s)){
// unsigned char col[4], selectedCol[4], activeCol[4];
// UI_GetThemeColor3ubv(TH_TRANSFORM, col);
@@ -943,22 +1006,40 @@
/* -- MESH SNAPPING -- */
+/* SnapMesh isn't really a class, but rather a collection of functions
+ *designed to operate on one type (Mesh) of instance of Snap defined by
+ *its s_type variable. It could be thought of as a subclass of Snap, introducing
+ *the necessary methods to snap with meshes*/
+
/*TODO: implement a better system for input/output with snaps to allow things such as
user configurable values for snaps like angles, number of sections for midpoint, and other things
*/
typedef struct {
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list