diff options
| -rw-r--r-- | doc/Images.txt | 3 | ||||
| -rw-r--r-- | doc/Imgbuf.txt | 177 | ||||
| -rw-r--r-- | doc/Makefile.am | 6 | ||||
| -rw-r--r-- | doc/Selection.txt | 149 |
4 files changed, 5 insertions, 330 deletions
diff --git a/doc/Images.txt b/doc/Images.txt index 6a36e6f5..62082e48 100644 --- a/doc/Images.txt +++ b/doc/Images.txt @@ -1,5 +1,8 @@ January 2009, --Jcid +Update June 2015: See also doc/dw-images-and-backgrounds.doc, or +../html/dw-images-and-backgrounds.html (generated by doxygen). + ------ IMAGES ------ diff --git a/doc/Imgbuf.txt b/doc/Imgbuf.txt deleted file mode 100644 index f4a56660..00000000 --- a/doc/Imgbuf.txt +++ /dev/null @@ -1,177 +0,0 @@ -Aug 2004, S.Geerken@ping.de - -============= -Image Buffers -============= - -General -======= - -Image buffers depend on the platform (see DwRender.txt), but have a -general, platform independant interface, which is described in this -section. The next section describes the Gdk version of Imgbuf. - -The structure ImgBuf will become part of the image processing, between -image data decoding and the widget DwImage. Its purposes are - - 1. storing the image data, - 2. handling scaled versions of this buffer, and - 3. drawing. - -The latter must be done independently from the window. - -Storing Image Data ------------------- -Imgbuf supports five image types, which are listed in the table -below. The representation defines, how the colors are stored within -the data, which is passed to a_Imgbuf_copy_row(). - - | bytes per | - type | pixel | representation - ---------------+-----------+------------------------- - RGB | 3 | red, green, blue - RGBA | 4 | red, green, blue, alpha - gray | 1 | gray value - indexed | 1 | index to colormap - indexed alpha | 1 | index to colormap - -The last two types need a colormap, which is set by -a_Imgbuf_set_cmap(), which must be called before -a_Imgbuf_copy_row(). This function expects the colors as 32 bit -unsigned integers, which have the format 0xrrbbgg (for indexed -images), or 0xaarrggbb (for indexed alpha), respectively. - -Scaling -------- -The buffer with the original size, which was created by -a_Imgbuf_new(), is called root buffer. Imgbuf provides the ability to -scale buffers. Generally, both root buffers, as well as scaled -buffers, may be shared, memory management is done by reference -counters. - -Via a_Imgbuf_get_scaled_buf(), you can retrieve a scaled buffer. The -way, how this function works in detail, is described in the code, but -generally, something like this works always, in an efficient way: - - old_buf = cur_buf; - cur_buf = a_Imgbuf_get_scaled_buf(old_buf, with, height); - a_Imgbuf_unref (old_buf); - -Old_buf may both be a root buffer, or a scaled buffer. - -(As an exception, there should always be a reference on the root -buffer, since scaled buffers cannot exist without the root buffer, but -on the other side, do not hold references on it. So, if in the example -above, old_buf would be a root buffer, and there would, at the -beginning, only be one reference on it, new_buf would also be -destroyed, along with old_buf. Therefore, an external reference must -be added to the root buffer, which is in dillo done within the dicache -module.) - -The root buffer keeps a list of all children, and all operations -operating on the image data (a_Imgbuf_copy_row() and -a_Imgbuf_set_cmap()) are delegated to the scaled buffers, when -processed, and inherited, when a new scaled buffer is created. This -means, that they must only be performed for the root buffer. - -Drawing -------- -There are two situations, when drawing is necessary: - - 1. To react on expose events, the function a_Imgbuf_draw() can be - used. Notice that the exact signature of this function is - platform dependant. - - 2. When a row has been copied, it has to be drawn. To determine the - area, which has to be drawn, the function - a_Imgbuf_get_row_area() should be used. In dillo, the dicache - module will first call a_Img_copy_row(), and then call - a_Dw_image_draw_row() for the images connected to this image - buffer. a_Dw_image_draw_row() will then call - p_Dw_widget_queue_draw(), with an area determined by - a_Imgbuf_get_row_area(). - - -The Gdk Implementation -====================== - -The Gdk implementation is used by the Gtk+ platform. [... todo] - - -Global Scalers -============== - -In some cases, there is a context, where images have to be scaled -often, by a relatively constant factor. For example, the preview -window (GtkDwPreview) draws images via the Imgbuf draw functions, but -uses scaled buffers. Scaling such a buffer each time it is needed, -causes huge performance losses. On the other hand, if the preview -window would keep these scaled buffers (e.g. by lazy mapping of the -original buffer to the scaled buffer), the scaled buffers get never -freed, since the view is not told about, when the original buffer is -not needed anymore. (n.b., that currently, the scaled buffers are -destroyed, when the original buffer is destroyed, but this may change, -and even this would leave "zombies" in this mapping structure, where -the values refer to dead pointers). - -It is sufficient, that references on the scaled buffers are referred -somehow, so that they do not get destroyed between different -usages. The caller (in this case the preview) simply requests a scaled -buffer, but the Imgbuf returns this from the list of already scaled -buffers. - -These references are hold by special structures, which are called -"scalers". There are two types of scalers, local scalers, which are -bound to image buffers, and global scalers, which refer to multiple -scalers. - -What happens in different situations: - - - The caller (e.g. the preview) requests a scaled buffer. For this, - it uses a special method, which also passes the global image - scaler, which was created before (for the preview, there is a 1-1 - association). The Imgbuf uses this global image scaler, to - identify the caller, and keeps a list of them. If this global - scaler is not yet in the list, it is added, and a local scaler is - created. - - - - - - -There are three images in the page, i1a, i1b, and i2. I1a and i1b -refer to the same image recource, represented by the root image buffer -iba, which original size is 200 x 200. I1a is displayed in original -size, while i1b is displayed at 100 x 100. I2 refers to an other -recource, ibb, which has the size 300 x 300. I2 is shown in original -size. - - - :DwRenderLayout ------------------- :DwPage ----------. - / \ | - ,----' `----. ,------ i1a:DwImage --+ - / \ | | - view1:GtkDwViewport view2:GtkDwPreview | ,---- i1b:DwImage --| - | | | | - ,------------------------------' | | ,-- i2: DwImage --' - | | | | - | ,-------------------------------------' | | - | | ,--------------------------------' | - | | | ,----' - | | | | - | V | V - | iba:Imgbuf | ibb:Imgbuf -- 30x30 - | | | V | ^ - | | +- 100x100 ,- 20x20 ,- 10x10 | | - | | | | ^ | ^ | | - | | `----------+----|---' | `--. ,--' - | | ,--------------' | | | - | | | ,------------------' | | - | | | | | | - | lca:ImgbufLSc lcb:ImgbufLSc - | (factor 1/10) (factor 1/10) - | \ / - | `-----------. ,-------------------' - | \ / - `------------------> scl:ImgbufGSc - (factor 1/10) diff --git a/doc/Makefile.am b/doc/Makefile.am index 8ade3d15..71c7c32d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -11,8 +11,8 @@ EXTRA_DIST = \ dw-widget-sizes.doc \ dw-changes.doc \ dw-images-and-backgrounds.doc \ - dw-dw-out-of-flow.doc \ - dw-dw-out-of-flow-2.doc \ + dw-out-of-flow.doc \ + dw-out-of-flow-2.doc \ fltk-problems.doc \ rounding-errors.doc \ uml-legend.doc \ @@ -38,9 +38,7 @@ EXTRA_DIST = \ HtmlParser.txt \ IO.txt \ Images.txt \ - Imgbuf.txt \ NC_design.txt \ - Selection.txt \ Dpid.txt \ CCCwork.txt \ README \ diff --git a/doc/Selection.txt b/doc/Selection.txt deleted file mode 100644 index 7904bd94..00000000 --- a/doc/Selection.txt +++ /dev/null @@ -1,149 +0,0 @@ -Apr 2003, S.Geerken@ping.de -Last update: Dec 2004 - -========= -Selection -========= - -The selection module (selection.[ch]) handles selections, as well as -activation of links, which is closely related. - - -General Overview -================ - -The selection module defines a structure "Selection", which is -associated to GtkDwViewport, and so to a widget tree. The selection -state is controlled by "abstract events", which are sent by single -widgets by calling one of the following functions: - - a_Selection_button_press for button press events, - a_Selection_button_release for button release events, and - a_Selection_button_motion for motion events (with pressed mouse - button). - -The widget must construct simple iterators (DwIterator), which will be -transferred to extended iterators (DwExtIterator), see below for more -details. All event handling functions have the same signature, the -arguments in detail are: - - - DwIterator *it the iterator pointing on the item under - the mouse pointer, - - gint char_pos the exact (character) position within - the iterator, - - gint link if this item is associated with a link, - its number (see DwImage, section - "signals" for the meaning), otherwise - -1, - - GdkEventButton *event the event itself; only the button is - used, - - gboolean within_content TRUE, if there is some selectable - content unter the mouse cursor; if set - to FALSE, the "full screen" feature is - used on double click. - -In some cases, char_pos would be difficult to determine. E.g., when -the DwPage widget decides that the user is pointing on a position -_at_the_end_ of an image (DwImage), it constructs a simple iterator -pointing on this image widget. In a simple iterator, that fact that -the pointer is at the end, would be represented by char_pos == 1. But -when transferring this simple iterator into an extended iterator, this -simple iterator is discarded and instead the stack has an iterator -pointing to text at the top. As a result, only the first letter of the -ALT text would be copied. - -To avoid this problem, widgets should in this case pass SELECTION_EOW -(end of word) as char_pos, which is then automatically reduced to the -actual length of the extended(!) iterator. - -The return value is the same as in DwWidget event handling methods. -I.e., in most cases, they should simply return it. The events -"link_pressed", "link_released" and "link_clicked" (but not -"link_entered") are emitted by these functions, so that widgets which -let the selection module handle links, should only emit "link_entered" -for themselves. (See DwImage.txt for a description of this.) - - -Selection State -=============== - -Selection interferes with handling the activation of links, so the -latter is also handled by the selection module. Details are based on -following guidelines: - - 1. It should be simple to select links and to start selection in - links. The rule to distinguish between link activation and - selection is that the selection starts as soon as the user leaves - the link. (This is, IMO, a useful feature. Even after drag and - drop has been implemented in dillo, this should be somehow - preserved.) - - 2. The selection should stay as long as possible, i.e., the old - selection is only cleared when a new selection is started. - -The latter leads to a model with two states: the selection state and -the link handling state. - -The general selection works, for events not pointing on links, like -this (numbers in parantheses after the event denote the button, "n" -means arbitrary button): - - motion(1) - ,-----. - | | - press(1) on non-link V | - NONE -----------------------> SELECTING <----------------. - ^ | | - | | release(1) | - | | | press(1) - | no V yes | - `----------------------- Anything selected? --------> SELECTED - -The selected region is represented by two DwExtIterators. - -Links are handled by a different state machine: - - ,-----------------------------. - | | - | Switch to selection - | (SELECTING) for n == 1. - | ^ - | | no - | | yes - | Still the same link? --. - | ^ | - | | | - | | motion(n) | - V press(n) on links | | - NONE ---------------------> PRESSED(n) <-----' - ^ | - | | release(n) - | | - | V yes - | Still the same link? -----------------. - | | | - | | no V - | V Send "clicked" signal. - | Switch to selection | - | (SELECTED) for n == 1. | - | | | - |`----------------------------' | - | | - `----------------------------------------------------------' - -Switching to selection simply means that the selection state will -eventually be SELECTED/SELECTING, with the original and the actual -position making up the selection region. This happens for button 1, -events with buttons other than 1 do not affect selection at all. - - -TODO -==== - -* a_Selection_button_motion currently always assumes that button 1 has - been pressed (since otherwise it would not do anything). This should - be made a bit cleaner. - -* The selection should be cleared, when the user selects something - somewhere else (perhaps switched into "non-active" mode, as some - Gtk+ widgets do). |