Adding upstream version 2.10.36.upstream/2.10.36

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 313 insertions, 0 deletions

diff --git a/plug-ins/gfig/README b/plug-ins/gfig/README
new file mode 100644
index 0000000..36076e8
--- /dev/null
+++ b/plug-ins/gfig/README
@@ -0,0 +1,313 @@
+Objects
++++++++
+
+The plug-in allows you to draw the following shapes:-
+
+Lines
+Circles
+Ellipses
+n sided regular polygons (n >=3)
+Curves (arcs)
+Spirals
+N pointed stars
+Simple Beizer curves
+
+An object is constructed as a number of control points and these are used 
+to select the object on the drawing area once it has been created.
+
+The drawing area preview is currently set to 
+
+	MIN(650 x 650,img_width x img_height). 
+
+You can change this altering the PREVIEW_SIZE item in the source code. 
+
+Operations
+++++++++++
+
+The following operations can be performed on objects:-
+
+The objects can either be moved independently around the drawing area or 
+all together.
+
+Each control point can be moved.
+
+Objects can be copied.
+
+Objects can be deleted.
+
+N sided Polygons can be split into N line segments. This also works for N 
+pointed stars.
+
+The drawing area can be scaled.
+
+Control points can be hidden.
+
+To aid alignment of objects a "grid" can be placed on the drawing area.
+This can be either a normal rectangular grid or a polar type grid centered 
+in the drawing area. 
+The spacings of the grid can be changed as well as the colors used to draw the
+grid lines. When "Snap to grid" is checked then all operations will be 
+constrained to fall on a grid intersection. (Fun when using the polar grid).
+Additionally the third mouse button will constrain the point movement to be
+on a horiz/vert (for rect grid) or radial/radius (for polar) only when 
+"Snap to grid" is set.
+
+The image that was selected when Gfig was started can also be shown (scaled) in
+the drawing area. (Options tag).
+
+Painting tab
+++++++++++++
+
+There are three possible mode when painting.
+
+1) Brush
+2) Selection
+3) Selection+fill 
+
+Brush
+~~~~~
+When the paint button is pressed each object will be rendered/drawn onto 
+the image using the currently selected ink color. The objects can be drawn 
+onto the original layer or onto a new layer (either a single layer or 
+multiple layers - latter is good for animations). When new layers are 
+created the background can either be:-
+	
+Transparent.
+Background (the current BG color).
+White.
+Copy.
+
+The last option means that the layer is duplicated from the previous layer 
+before the draw operation is performed (re good for animations).
+
+Lines can be drawn in reverse order. This means that reg polygons/curves/lines 
+that are normally constructed of lines can be drawn starting at either "end". 
+This is only noticeable when the current brush has fading turned on.
+The "Approx Circles/Ellipses" toggle allows the same effects when drawing these
+types of objects.
+
+Note that in the current version any selections present in the image are first 
+de-selected when Gfig starts up. This is because selections are used to 
+draw circles and ellipses (unless the Approx. Circles & Ellipses toggle is set).
+
+Selection
+~~~~~~~~~
+With this method closed selections are made of the objects. See selection
+tab for more details.
+
+Selections can only be made on the current layer.
+
+Selection+Fill
+~~~~~~~~~~~~~~
+This method first selects the objects and then fills the selection area. The
+selection tab gives more details on how the selections are filled.
+
+
+Brush Tab
++++++++++
+
+This tab now contains a preview of the selected brush in black ink. If the
+brush is too large to fit in the preview use the mouse button to "move" it
+around (as with the brush dialog in the main GIMP - until that brush 
+patch went in!).
+
+Four types of brush can be used:-
+
+Normal brush
+~~~~~~~~~~~~
+Simply paints with the current brush - honors fading if any
+The Fade option allows the "brush fading" to be selected. I am sure that some
+nifty anims can be created with this option. 
+
+Pencil brush
+~~~~~~~~~~~~
+Same as the GIMPS pencil. 
+
+Airbrush
+~~~~~~~~
+As GIMPS airbrush. The "pressure" can be specified and this is reflected in the
+preview window.
+
+Pattern
+~~~~~~~
+The lines are drawn with the currently selected pattern. The preview will
+show this pattern.
+
+Note a patch to enable a couple of "hidden" paintbrush features was recently
+posted to the GIMP developers list. The patch only allowed these features
+to be called via the UI and not the PDB so they cannot be used by Gfig. If they were exported via the PDB then they would have probably broken a number of 
+scripts and Gfig itself (number of args changes on the PDB call).
+
+Select tab
+++++++++++
+
+This is enabled when using either Selection or Selection+fill types when
+painting objects.
+
+The anti aliasing and feather toggles apply to the selection made when 
+"painting" the objects. The feather radius can be changed.
+
+The default selection mode is to add to the current selection so each object
+add to the overall selection. The other selection modes are also possible
+but you must bear in mind the following:-
+
+Subtraction/Intersection will not produce any selection if no selection is 
+elect the area in the target window (AFTER starting Gfig up) and then paint 
+using this method.
+
+Replace will leave only the last object selection.
+
+When the paint type is selection+fill then the objects will be selected 
+and then filled. The opacity of the fill can be chosen. By default a fill
+is performed after each section. If filling onto a single layer
+then the fill will accumulate on the first objects painted. This will be 
+noticeable when opacity != 100. To get around this then use replace mode
+OR use a new layer for each selection/fill. (Paint tab). Additionally you can
+set the fill to be performed after ALL objects have been selected (useful
+for intersection type selections).
+
+Selection of non-closed objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For objects that are not closed the first & last points will be joined 
+together to form the closed selection. For arcs you can either fill
+as segments or sectors. Note straight lines will not cause any selection to be
+made. This can be a little confusing when filling since the whole canvas will
+be filled if any straight lines are present on it.
+
+
+Scaling
++++++++
+
+When Gfig first comes up the selected group of objects are automatically scaled 
+upwards to the image size. (If the source image is < 256*256 then no automatic 
+scaling is performed - change PREVIEW_SIZE in source to alter this values).
+By toggling the scale button the objects can then be scaled in the drawing 
+area. This scaling will be reflected when the objects are drawn.
+To reposition the objects on the drawing area use SHIFT + MOVE_OBJ operation.
+
+
+Other ops
++++++++++
+
+Double click on reg polygon object selection to get dialog with slider to 
+selected the number of sides to draw.
+
+Double click on star object selection to get dialog with slider to 
+selected the number of points the star will have.
+
+Double click on spiral object selection to get dialog with slider to 
+selected the number of turns the spiral will have and it direction.
+
+Double click on bezier object selection to get dialog which allows you to
+control how the curve is displayed and if it is closed.
+
+SHIFT + MOVE_PNT will break a reg polygon or star into a number of 
+connected lines.
+
+When drawing lines if the SHIFT modifier is used then connected lines 
+can be drawn.
+
+SHIFT + MOVE_OBJ will move all objects. Note if "snap to grid" is selected then
+the new point will be constrained to fall on a grid intersection.
+
+Mouse button 3 + "snap to grid" will constrain the point to fall on one of the
+two gridlines it was originally on.
+
+The ">" and "<" buttons allow you to selective move through each of the 
+objects in the collection. The "==" returns the display to normal. If the
+"paint" button is pressed then only the single object displayed will be 
+drawn into the target window. Also when in this mode pressing the shift button
+will temporarily show all the objects in the collection.
+
+The the options tab there is now a toggle that allows you to turn the 
+position display on and off.
+
+Gfig objects
+++++++++++++
+
+The upper right part of gfig contains a scroll region when different 
+collection of objects can be found. When button 1 is pressed on an entry 
+the small preview window will be updated with the objects contained in 
+the selected figure. These objects can then be loaded into the main window 
+by using the "Edit" button or the "Merge" button. In the former case 
+the objects area will first be cleared before the new objects
+are added. In the latter case the objects will be merged into the drawing area.
+
+When a collection of objects is altered to small image of a floppy disc 
+will be placed next to the entry signifying that this collection needs to be 
+saved. If a red cross appears here then the file associated with the 
+entry is read only and cannot be saved to (it can be copied however).
+
+Button 3 brings up a popup menu that allows collections to be saved away to 
+different files. (Accel. keys also exist for some functions).
+
+The buttons on the right of the list area allow the following operations:-
+
+Rescan:-
+This popus up a window which allows you to add directories to the internal 
+gfig-path.  A (re)scan of these directories can the performed. Note any 
+modification to the gfig-path will NOT be mirrored in your ~/.gimp/gimprc file.
+
+Load:-
+Allows you to load a single collection of objects.
+
+New:-
+Create a new collection. Note that until this is saved away to a file then no
+filename will be associated with it. (See status area).
+
+Delete:-
+Popups a dialog asking if you wish to delete the entry selected in the list 
+box as well as on disc.
+
+Additionally button 3 over the list area allows the following:-
+
+Save as...:-
+Save collection to new filename. The collections filename is also 
+changed to this new name. The original name is NOT deleted from the disc 
+but it is effectively removed from the list selection area (actually it 
+is overwritten internally).
+
+Save:-
+Save the currently selected entry to disc.
+
+Copy:-
+Make a copy of the collection.
+
+Edit:-
+Same as the "Edit button".
+
+Double click on entry with Button 1 popups up a dialog that allows you to 
+modify the nme of an entry (similar to other list areas in GIMP).
+
+Bezier
+~~~~~~
+
+OK my maths is a little rusty. The bezier stuff is only very simple. However...
+I have tried to abstract as much as possible the bezier calculations from
+the drawing of the control points / painting on the screen and in the target
+window. 
+
+The bezier function is defined as:-
+
+void
+DrawBezier (gdouble (*points)[2], gint np, gdouble mid, gint depth)
+{
+...
+}
+
+Points an array of pairs of doubles that define the control points
+np is the number of points. Mid is always starts as 0.5 - and depth
+defines how deep the recursion should go when calculating the line points.
+
+The function should call fp_pnt_add() when a point on the curve has been
+calculated. 
+
+If anyone would like to produce a better/faster function then you
+should be able to replace the DrawBezier function. (Only the first two args
+are really needed). 
+
+The algorithm the current code is based on was obtained by looking 
+at the many many examples out on the web.
+(Bezier drawing seems to be topic of the year for computer degrees 
+and people learning java!!!)
+