From 3c57dd931145d43f2b0aef96c4d178135956bf91 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 05:13:10 +0200 Subject: Adding upstream version 2.10.36. Signed-off-by: Daniel Baumann --- plug-ins/gfig/README | 313 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 plug-ins/gfig/README (limited to 'plug-ins/gfig/README') 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!!!) + -- cgit v1.2.3