[UFRaw-CVS] ufraw ufraw.h, 1.152, 1.153 ufraw_lens_ui.c, 1.35, 1.36 ufraw_lensfun.cc, 1.3, 1.4 ufraw_ufraw.c, 1.246, 1.247 ufraw_ui.h, 1.39, 1.40

[Udi F. <udi...@us...>]

Update of /cvsroot/ufraw/ufraw
In directory sfp-cvsdas-2.v30.ch3.sourceforge.com:/tmp/cvs-serv1472

Modified Files:
	ufraw.h ufraw_lens_ui.c ufraw_lensfun.cc ufraw_ufraw.c 
	ufraw_ui.h 
Log Message:
Add ufLensGeometry and ufTargetLensGeometry UFObjects.


Index: ufraw.h
===================================================================
RCS file: /cvsroot/ufraw/ufraw/ufraw.h,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -d -r1.152 -r1.153
--- ufraw.h	26 Feb 2010 07:01:04 -0000	1.152
+++ ufraw.h	27 Feb 2010 06:36:21 -0000	1.153
@@ -73,6 +73,8 @@
 extern UFName ufVignetting;
 extern UFName ufDistortion;
 extern UFName ufModel;
+extern UFName ufLensGeometry;
+extern UFName ufTargetLensGeometry;
 extern UFName ufRawImage;
 extern UFName ufRawResources;
 extern UFName ufCommandLine;

Index: ufraw_lensfun.cc
===================================================================
RCS file: /cvsroot/ufraw/ufraw/ufraw_lensfun.cc,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- ufraw_lensfun.cc	26 Feb 2010 07:01:04 -0000	1.3
+++ ufraw_lensfun.cc	27 Feb 2010 06:36:21 -0000	1.4
@@ -21,6 +21,10 @@
 #include <math.h>
 
 #ifdef HAVE_LENSFUN
+
+#define UF_LF_TRANSFORM ( \
+	LF_MODIFY_DISTORTION | LF_MODIFY_GEOMETRY | LF_MODIFY_SCALE)
+
 namespace UFRaw {
 
 class Lensfun : public UFGroup {
@@ -60,10 +64,10 @@
     // The criteria is to have 2 or 3 significant digits.
     int precision;
     if (number > 10.0 && (int)(10*number)%10 != 0)
-        // Support focal length such as 10.5mm fisheye.
-        precision = MAX(-floor(log(number) / log(10) - 1.99), 0);
+	// Support focal length such as 10.5mm fisheye.
+	precision = MAX(-floor(log(number) / log(10) - 1.99), 0);
     else
-        precision = MAX(-floor(log(number) / log(10) - 0.99), 0);
+	precision = MAX(-floor(log(number) / log(10) - 0.99), 0);
     snprintf(buffer, _buffer_size, "%.*f", precision, number);
     return buffer;
 }
@@ -95,9 +99,9 @@
 	    *this << new UFString(ufPreset, _StringNumber(buffer, min));
 	int i = 0;
 	while (focalValues[i] < min && focalValues[i] != 0)
-	    i++; 
+	    i++;
 	if (Has(_StringNumber(buffer, focalValues[i])))
-	    i++; // Comparing string works better than comparing doubles.
+	    i++; // Comparing strings works better than comparing doubles.
 	while (focalValues[i] < max && focalValues[i] != 0) {
 	    *this << new UFString(ufPreset, _StringNumber(buffer,
 		    focalValues[i]));
@@ -137,7 +141,7 @@
 	while (apertureValues[i] < min && apertureValues[i] != 0)
 	    i++;
 	if (Has(_StringNumber(buffer, apertureValues[i])))
-	    i++; // Comparing string works better than comparing doubles.
+	    i++; // Comparing strings works better than comparing doubles.
 	while (apertureValues[i] != 0) {
 	    *this << new UFString(ufPreset, _StringNumber(buffer,
 		    apertureValues[i]));
@@ -400,6 +404,39 @@
     }
 };
 
+extern "C" { UFName ufLensGeometry = "LensGeometry"; }
+class LensGeometry : public UFArray {
+public:
+    explicit LensGeometry(UFName name = ufLensGeometry) : UFArray(name,
+	    lfLens::GetLensTypeDesc(LF_UNKNOWN, NULL)) {
+	for (lfLensType type = LF_UNKNOWN; ; type = lfLensType(type+1)) {
+	    const char *typeName = lfLens::GetLensTypeDesc(type, NULL);
+	    if (typeName == NULL)
+		break; // End of loop.
+	    *this << new UFString("Type", typeName);
+	}
+    }
+    void OriginalValueChangedEvent() {
+	ufraw_data *uf = ufraw_image_get_data(this);
+	if (uf == NULL)
+	    return;
+	Lensfun::Parent(*this).Transformation.Type = lfLensType(Index());
+	ufraw_invalidate_layer(uf, ufraw_transform_phase);
+    }
+};
+
+extern "C" { UFName ufTargetLensGeometry = "TargetLensGeometry"; }
+class TargetLensGeometry : public LensGeometry {
+public:
+    TargetLensGeometry() : LensGeometry(ufTargetLensGeometry) { }
+    void OriginalValueChangedEvent() {
+	ufraw_data *uf = ufraw_image_get_data(this);
+	if (uf == NULL)
+	    return;
+	ufraw_invalidate_layer(uf, ufraw_transform_phase);
+    }
+};
+
 extern "C" { UFName ufLensfun = "Lensfun"; }
 Lensfun::Lensfun() : UFGroup(ufLensfun), FocalLengthValue(0.0),
 	ApertureValue(0.0), DistanceValue(0.0) {
@@ -410,6 +447,8 @@
 	<< new TCA
 	<< new Vignetting
 	<< new Distortion
+	<< new LensGeometry
+	<< new TargetLensGeometry
     ;
 }
 
@@ -497,6 +536,56 @@
     Lensfun.Init();
 }
 
+void ufraw_convert_prepare_transform(ufraw_data *uf,
+	int width, int height, gboolean reverse, float scale)
+{
+    UFGroup &Image = *uf->conf->ufobject;
+    UFRaw::Lensfun &Lensfun =  static_cast<UFRaw::Lensfun &>(Image[ufLensfun]);
+    conf_data *conf = uf->conf;
+    if (uf->modifier != NULL)
+	uf->modifier->Destroy();
+    uf->modifier = lfModifier::Create(&Lensfun.Transformation,
+	    conf->camera->CropFactor, width, height);
+    if (uf->modifier == NULL)
+	return;
+
+    UFArray &targetLensGeometry = Lensfun[ufTargetLensGeometry];
+    uf->modFlags = uf->modifier->Initialize(&Lensfun.Transformation,
+	    LF_PF_U16, Lensfun.FocalLengthValue, Lensfun.ApertureValue,
+	    Lensfun.DistanceValue, scale,
+	    lfLensType(targetLensGeometry.Index()),
+	    UF_LF_TRANSFORM | LF_MODIFY_VIGNETTING, reverse);
+    if ((uf->modFlags & (UF_LF_TRANSFORM | LF_MODIFY_VIGNETTING)) == 0) {
+	uf->modifier->Destroy();
+	uf->modifier = NULL;
+    }
+}
+
+void ufraw_prepare_tca(ufraw_data *uf)
+{
+    UFGroup &Image = *uf->conf->ufobject;
+    UFRaw::Lensfun &Lensfun =  static_cast<UFRaw::Lensfun &>(Image[ufLensfun]);
+    ufraw_image_data *img = &uf->Images[ufraw_raw_phase];
+
+    if (uf->TCAmodifier != NULL)
+	uf->TCAmodifier->Destroy();
+    uf->TCAmodifier = lfModifier::Create(&Lensfun.Transformation,
+	    uf->conf->camera->CropFactor, img->width, img->height);
+    if (uf->TCAmodifier == NULL)
+	return;
+
+    UFArray &targetLensGeometry = Lensfun[ufTargetLensGeometry];
+    int modFlags = uf->TCAmodifier->Initialize(&Lensfun.Transformation,
+	    LF_PF_U16, Lensfun.FocalLengthValue, Lensfun.ApertureValue,
+	    Lensfun.DistanceValue, 1.0,
+	    lfLensType(targetLensGeometry.Index()),
+	    LF_MODIFY_TCA, false);
+    if ((modFlags & LF_MODIFY_TCA) == 0) {
+	uf->TCAmodifier->Destroy();
+	uf->TCAmodifier = NULL;
+    }
+}
+
 }
 
 } // namespace UFRaw

Index: ufraw_ui.h
===================================================================
RCS file: /cvsroot/ufraw/ufraw/ufraw_ui.h,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -d -r1.39 -r1.40
--- ufraw_ui.h	26 Feb 2010 07:01:04 -0000	1.39
+++ ufraw_ui.h	27 Feb 2010 06:36:21 -0000	1.40
@@ -126,10 +126,6 @@
     GtkWidget *LensTCATable, *LensTCADesc;
     /* The lens fix notebook vignetting page */
     GtkWidget *LensVignettingTable, *LensVignettingDesc;
-    /* The lens fix notebook geometry page */
-    GtkWidget *LensGeometryTable, *LensFromGeometryDesc, *LensToGeometryDesc;
-    /* The 'from' and 'to' geometry selectors */
-    GtkWidget *LensFromGeometrySel, *LensToGeometrySel;
     /* The hbox containing focal, aperture, distance combos */
     GtkWidget *LensParamBox;
 #endif /* HAVE_LENSFUN */

Index: ufraw_lens_ui.c
===================================================================
RCS file: /cvsroot/ufraw/ufraw/ufraw_lens_ui.c,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -d -r1.35 -r1.36
--- ufraw_lens_ui.c	26 Feb 2010 07:01:04 -0000	1.35
+++ ufraw_lens_ui.c	27 Feb 2010 06:36:21 -0000	1.36
@@ -170,15 +170,6 @@
 	    0, gtk_get_current_event_time());
 }
 
-/* Update all lens model-related controls to reflect current model */
-static void lens_update_controls(preview_data *data)
-{
-    gtk_combo_box_set_active(GTK_COMBO_BOX(data->LensFromGeometrySel),
-	    CFG->lens->Type);
-    gtk_combo_box_set_active(GTK_COMBO_BOX(data->LensToGeometrySel),
-	    CFG->cur_lens_type);
-}
-
 static void combo_entry_new(UFObject *object, GtkWidget *box,
 	const char *labelText, const char *tooltip)
 {
@@ -270,7 +261,6 @@
     UFObject *lensfun = ufgroup_element(CFG->ufobject, ufLensfun);
     ufraw_lensfun_interpolate(lensfun, lens);
     lens_set(data);
-    lens_update_controls(data);
 }
 
 static void lens_menu_fill(preview_data *data, const lfLens *const *lenslist)
@@ -552,7 +542,7 @@
 
 /* --- Lens geometry page --- */
 
-static void geometry_model_changed(GtkComboBox *widget, preview_data *data)
+static void geometry_model_changed(GtkComboBox *widget, GtkLabel *label)
 {
     lfLensType type = gtk_combo_box_get_active(widget);
 
@@ -560,88 +550,57 @@
     if (!lf_get_lens_type_desc(type, &details))
 	return; // should never happen
 
-    lfLensType *target = (lfLensType *)g_object_get_data(G_OBJECT(widget),
-	    "LensType");
-
-    *target = type;
-
-    if (target == &CFG->cur_lens_type)
-	gtk_label_set_text(GTK_LABEL(data->LensToGeometryDesc), details);
-    else
-	gtk_label_set_text(GTK_LABEL(data->LensFromGeometryDesc), details);
-
-    ufraw_invalidate_layer(data->UF, ufraw_transform_phase);
-    render_preview(data);
+    gtk_label_set_text(label, details);
 }
 
-static void fill_geometry_page(preview_data *data, GtkWidget *page)
+static GtkWidget *fill_geometry_page(UFObject *ufobject)
 {
-    data->LensGeometryTable = gtk_table_new(10, 1, FALSE);
-    gtk_box_pack_start(GTK_BOX(page),
-	    data->LensGeometryTable, TRUE, TRUE, 0);
+    UFObject *lensfun = ufgroup_element(ufobject, ufLensfun);
+    GtkTable *geometryTable = GTK_TABLE(gtk_table_new(10, 1, FALSE));
 
-    /* Add the model combobox */
+    /* Lens geometry combobox */
     GtkWidget *label = gtk_label_new(_("Lens geometry:"));
     gtk_misc_set_alignment(GTK_MISC(label), 1.0, 0.5);
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable), label,
-	    0, 1, 0, 1, GTK_FILL, 0, 5, 0);
-    data->LensFromGeometrySel = gtk_combo_box_new_text();
-    uf_widget_set_tooltip(data->LensFromGeometrySel,
+    gtk_table_attach(geometryTable, label, 0, 1, 0, 1, GTK_FILL, 0, 5, 0);
+    UFObject *lensGeometry = ufgroup_element(lensfun, ufLensGeometry);
+    GtkWidget *combo = ufarray_combo_box_new(lensGeometry);
+    uf_widget_set_tooltip(combo,
 	    _("The geometry of the lens used to make the shot"));
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable),
-	    data->LensFromGeometrySel, 1, 2, 0, 1,
+    gtk_table_attach(geometryTable, combo, 1, 2, 0, 1,
 	    GTK_EXPAND | GTK_FILL, 0, 0, 0);
 
-    data->LensFromGeometryDesc = gtk_label_new("");
-    gtk_label_set_line_wrap(GTK_LABEL(data->LensFromGeometryDesc), TRUE);
-    gtk_label_set_ellipsize(GTK_LABEL(data->LensFromGeometryDesc),
-	    PANGO_ELLIPSIZE_END);
-    gtk_label_set_selectable(GTK_LABEL(data->LensFromGeometryDesc), TRUE);
-    gtk_misc_set_alignment(GTK_MISC(data->LensFromGeometryDesc), 0.5, 0.5);
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable),
-	    data->LensFromGeometryDesc, 0, 2, 1, 2,
+    GtkWidget *description = gtk_label_new("");
+    gtk_label_set_line_wrap(GTK_LABEL(description), TRUE);
+    gtk_label_set_ellipsize(GTK_LABEL(description), PANGO_ELLIPSIZE_END);
+    gtk_label_set_selectable(GTK_LABEL(description), TRUE);
+    gtk_misc_set_alignment(GTK_MISC(description), 0.5, 0.5);
+    gtk_table_attach(geometryTable, description, 0, 2, 1, 2,
 	    GTK_EXPAND | GTK_FILL, 0, 0, 10);
+    g_signal_connect(G_OBJECT(combo), "changed",
+	    G_CALLBACK(geometry_model_changed), description);
 
+    /* Target lens geometry combobox */
     label = gtk_label_new(_("Target geometry:"));
     gtk_misc_set_alignment(GTK_MISC(label), 1.0, 0.5);
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable), label,
-	    0, 1, 2, 3, GTK_FILL, 0, 5, 0);
-    data->LensToGeometrySel = gtk_combo_box_new_text();
-    uf_widget_set_tooltip(data->LensToGeometrySel,
-	    _("The target geometry for output image"));
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable),
-	    data->LensToGeometrySel, 1, 2, 2, 3,
+    gtk_table_attach(geometryTable, label, 0, 1, 2, 3, GTK_FILL, 0, 5, 0);
+    UFObject *targetLensGeometry =
+	    ufgroup_element(lensfun, ufTargetLensGeometry);
+    combo = ufarray_combo_box_new(targetLensGeometry);
+    uf_widget_set_tooltip(combo, _("The target geometry for output image"));
+    gtk_table_attach(geometryTable, combo, 1, 2, 2, 3,
 	    GTK_EXPAND | GTK_FILL, 0, 0, 0);
 
-    data->LensToGeometryDesc = gtk_label_new("");
-    gtk_label_set_line_wrap(GTK_LABEL(data->LensToGeometryDesc), TRUE);
-    gtk_label_set_ellipsize(GTK_LABEL(data->LensToGeometryDesc),
-	    PANGO_ELLIPSIZE_END);
-    gtk_label_set_selectable(GTK_LABEL(data->LensToGeometryDesc), TRUE);
-    gtk_misc_set_alignment(GTK_MISC(data->LensToGeometryDesc), 0.5, 0.5);
-    gtk_table_attach(GTK_TABLE(data->LensGeometryTable),
-	    data->LensToGeometryDesc, 0, 2, 3, 4,
+    description = gtk_label_new("");
+    gtk_label_set_line_wrap(GTK_LABEL(description), TRUE);
+    gtk_label_set_ellipsize(GTK_LABEL(description), PANGO_ELLIPSIZE_END);
+    gtk_label_set_selectable(GTK_LABEL(description), TRUE);
+    gtk_misc_set_alignment(GTK_MISC(description), 0.5, 0.5);
+    gtk_table_attach(geometryTable, description, 0, 2, 3, 4,
 	    GTK_EXPAND | GTK_FILL, 0, 0, 10);
+    g_signal_connect(G_OBJECT(combo), "changed",
+	    G_CALLBACK(geometry_model_changed), description);
 
-    int i;
-    for (i = 0; ; i++) {
-	lfLensType type = LF_UNKNOWN + i;
-	const char *type_name = lf_get_lens_type_desc(type, NULL);
-	if (type_name == NULL)
-	    break;
-	gtk_combo_box_append_text(GTK_COMBO_BOX(data->LensFromGeometrySel),
-		type_name);
-	gtk_combo_box_append_text(GTK_COMBO_BOX(data->LensToGeometrySel),
-		type_name);
-    }
-    g_object_set_data(G_OBJECT(data->LensFromGeometrySel), "LensType",
-	    &CFG->lens->Type);
-    g_signal_connect(G_OBJECT(data->LensFromGeometrySel), "changed",
-	    G_CALLBACK(geometry_model_changed), data);
-    g_object_set_data(G_OBJECT(data->LensToGeometrySel), "LensType",
-	    &CFG->cur_lens_type);
-    g_signal_connect(G_OBJECT(data->LensToGeometrySel), "changed",
-	    G_CALLBACK(geometry_model_changed), data);
+    return GTK_WIDGET(geometryTable);
 }
 
 /**
@@ -723,9 +682,8 @@
     gtk_notebook_set_current_page(subnb, pageNum);
 
     subpage = notebook_page_new(subnb, _("Lens geometry"), "geometry");
-    fill_geometry_page(data, subpage);
-
-    lens_update_controls(data);
+    gtk_box_pack_start(GTK_BOX(subpage), fill_geometry_page(CFG->ufobject),
+	    TRUE, TRUE, 0);
 }
 
 #endif /* HAVE_LENSFUN */

Index: ufraw_ufraw.c
===================================================================
RCS file: /cvsroot/ufraw/ufraw/ufraw_ufraw.c,v
retrieving revision 1.246
retrieving revision 1.247
diff -u -d -r1.246 -r1.247
--- ufraw_ufraw.c	26 Feb 2010 07:01:04 -0000	1.246
+++ ufraw_ufraw.c	27 Feb 2010 06:36:21 -0000	1.247
@@ -30,9 +30,6 @@
 void (*ufraw_progress)(int what, int ticks) = NULL;
 
 #ifdef HAVE_LENSFUN
-/* What about LF_MODIFY_ALL? */
-#define UF_LF_ALL (LF_MODIFY_TCA | LF_MODIFY_VIGNETTING | \
-	LF_MODIFY_DISTORTION | LF_MODIFY_GEOMETRY | LF_MODIFY_SCALE)
 #define UF_LF_TRANSFORM ( \
 	LF_MODIFY_DISTORTION | LF_MODIFY_GEOMETRY | LF_MODIFY_SCALE)
 void ufraw_lensfun_init(ufraw_data *uf);
@@ -40,7 +37,7 @@
 	ufraw_image_data *img, UFRectangle *area);
 static void ufraw_convert_image_tca(ufraw_data *uf, ufraw_image_data *img,
 	ufraw_image_data *outimg, UFRectangle *area);
-static void ufraw_prepare_tca(ufraw_data *uf);
+void ufraw_prepare_tca(ufraw_data *uf);
 #endif
 static void ufraw_image_format(int *colors, int *bytes, ufraw_image_data *img,
 	const char *formats, const char *caller);
@@ -1348,47 +1345,18 @@
     }
 }
  
-static void ufraw_convert_prepare_transform(ufraw_data *uf,
-	int width, int height, gboolean reverse, float scale)
-{
 #ifdef HAVE_LENSFUN
-    conf_data *conf = uf->conf;
-    if (uf->modifier != NULL)
-	lf_modifier_destroy(uf->modifier);
-    uf->modifier = NULL;
-
-    if (conf->camera == NULL || conf->lens == NULL)
-	return;
-
-    uf->modifier = lf_modifier_new(conf->lens, conf->camera->CropFactor,
-	    width, height);
-    if (uf->modifier == NULL)
-	return;
-
-    uf->modFlags = lf_modifier_initialize(uf->modifier, conf->lens,
-	    LF_PF_U16, conf->focal_len, conf->aperture, conf->subject_distance,
-	    scale, conf->cur_lens_type,
-	    UF_LF_TRANSFORM | LF_MODIFY_VIGNETTING, reverse);
-    if ((uf->modFlags & UF_LF_ALL) == 0) {
-	lf_modifier_destroy(uf->modifier);
-	uf->modifier = NULL;
-    }
-#else /* HAVE_LENSFUN */
-    (void)uf;
-    (void)width;
-    (void)height;
-    (void)reverse;
-    (void)scale;
-#endif /* HAVE_LENSFUN */
-}
+void ufraw_convert_prepare_transform(ufraw_data *uf,
+	int width, int height, gboolean reverse, float scale);
+#endif
 
 static void ufraw_convert_prepare_transform_buffer(ufraw_data *uf,
 	ufraw_image_data *img, int width, int height)
 {
     const int iWidth = uf->initialWidth;
     const int iHeight = uf->initialHeight;
-    ufraw_convert_prepare_transform(uf, iWidth, iHeight, TRUE, 1.0);
 #ifdef HAVE_LENSFUN
+    ufraw_convert_prepare_transform(uf, iWidth, iHeight, TRUE, 1.0);
     if (uf->conf->rotationAngle == 0 &&
 	(uf->modifier == NULL || !(uf->modFlags & UF_LF_TRANSFORM)))
 #else
@@ -1400,7 +1368,9 @@
 	img->width = width;
 	img->height = height;
 	// We still need the transform for vignetting
+#ifdef HAVE_LENSFUN
 	ufraw_convert_prepare_transform(uf, width, height, FALSE, 1.0);
+#endif
 	uf->rotatedWidth = iWidth;
 	uf->rotatedHeight = iHeight;
 	uf->autoCropWidth = iWidth;
@@ -1468,7 +1438,9 @@
     int newWidth = uf->rotatedWidth * width / iWidth;
     int newHeight = uf->rotatedHeight * height / iHeight;
     ufraw_image_init(img, newWidth, newHeight, 8);
+#ifdef HAVE_LENSFUN
     ufraw_convert_prepare_transform(uf, width, height, FALSE, scale);
+#endif
 }
 
 /*
@@ -1515,34 +1487,6 @@
     }
 }
 
-#ifdef HAVE_LENSFUN
-static void ufraw_prepare_tca(ufraw_data *uf)
-{
-    ufraw_image_data *img = &uf->Images[ufraw_raw_phase];
-
-    if (uf->TCAmodifier != NULL)
-	lf_modifier_destroy(uf->TCAmodifier);
-    uf->TCAmodifier = NULL;
-
-    if (uf->conf->camera == NULL || uf->conf->lens == NULL)
-	return;
-
-    uf->TCAmodifier = lf_modifier_new(uf->conf->lens,
-	    uf->conf->camera->CropFactor, img->width, img->height);
-    if (uf->TCAmodifier == NULL)
-	return;
-
-    int modFlags = lf_modifier_initialize(uf->TCAmodifier, uf->conf->lens,
-	    LF_PF_U16, uf->conf->focal_len, uf->conf->aperture,
-	    uf->conf->subject_distance, 1.0, uf->conf->cur_lens_type,
-	    LF_MODIFY_TCA, FALSE);
-    if ((modFlags & LF_MODIFY_TCA) == 0) {
-	lf_modifier_destroy(uf->TCAmodifier);
-	uf->TCAmodifier = NULL;
-    }
-}
-#endif
-
 /*
  * This function is very permissive in accepting NULL pointers but it does
  * so to make it easy to call this function: consider it documentation with