diff options
Diffstat (limited to 'doc/dw-images-and-backgrounds.doc')
| -rw-r--r-- | doc/dw-images-and-backgrounds.doc | 259 |
1 files changed, 173 insertions, 86 deletions
diff --git a/doc/dw-images-and-backgrounds.doc b/doc/dw-images-and-backgrounds.doc index 356652a6..8f07766a 100644 --- a/doc/dw-images-and-backgrounds.doc +++ b/doc/dw-images-and-backgrounds.doc @@ -1,10 +1,11 @@ /** \page dw-images-and-backgrounds Images and Backgrounds in Dw -<h2>General</h2> +Image Buffers +============= -Representation of the image data is delegated to dw::core::Imgbuf, see -there for details. Drawing is delegated to dw::core::View -(dw::core::View::drawImgbuf). +Representation of the image data is done by dw::core::Imgbuf, see +there for details. Drawing is done by dw::core::View +(dw::core::View::drawImage). Since dw::core::Imgbuf provides memory management based on reference counting, there may be an 1-to-n relation from image renderers (image @@ -15,61 +16,73 @@ dw::core::Imgbuf::copyRow) notify all renderers connected to the buffer. -<h2>Images</h2> +Image Renderer +============== + +Generally, there are no restrictions on how to manage +dw::core::Imgbuf; but to handle image data from web resources, the +interface dw::core::ImgRenderer should be implemented. It is again +wrapped by DilloImage (to make access from the C part possible, since +dw::core::ImgRenderer is written in C++), which is referenced by +DilloWeb. There are two positions where retrieving image data is +initiated: + +- Html_load_image: for embedded images (implemented by dw::Image, + which implements dw::core::ImgRenderer); +- StyleEngine::apply (search for "case + CSS_PROPERTY_BACKGROUND_IMAGE"): for backgrond images; there are + some implementations of dw::core::ImgRenderer within the context of + dw::core::style::StyleImage. + +Both are described in detail below. Notice that the code is quite +similar; only the implementation of dw::core::ImgRenderer differs. + +At this time, dw::core::ImgRenderer has got two methods (see more +documentation there): + +- dw::core::ImgRenderer::setBuffer, +- dw::core::ImgRenderer::drawRow, +- dw::core::ImgRenderer::finish, and +- dw::core::ImgRenderer::fatal. + + +Images +====== This is the simplest renderer, displaying an image. For each row to be drawn, -<ol> -<li> first dw::core::Imgbuf::copyRow, and then -<li> for each dw::Image, dw::Image::drawRow must be called, with the same - argument (no scaling is necessary). -</ol> +- first dw::core::Imgbuf::copyRow, and then +- for each dw::Image, dw::Image::drawRow must be called, with the same + argument (no scaling is necessary). dw::Image automatically scales the dw::core::Imgbuf, the root buffer should be passed to dw::Image::setBuffer. \see dw::Image for more details. -<h2>Future Extensions</h2> -(This is not implemented yet.) Rendering itself (image widgets and -background) will be abstracted, by a new interface -dw::core::ImageRenderer. In the current code for image decoding, this -interface will replace references to dw::Image, which implements -dw::core::ImageRenderer, in most cases. +Background Images +================= -<h2>Backgrounds</h2> +Since background images are style resources, they are associated with +dw::core::style::Style, as dw::core::style::StyleImage, which is +handled in a similar way (reference counting etc.) as +dw::core::style::Color and dw::core::style::Font, although it is +concrete and not platform-dependant. -(This is based on future extensions described above.) Since background -are style resources, they are associated with -dw::core::style::Style. For backgrounds, another level is needed, -because of the 1-to-n relation from dw::core::style::Style to -dw::core::Widget: +The actual renderer (passed to Web) is an instance of +dw::core::ImgRendererDist (distributes all calls to a set of other +instances of dw::core::ImgRenderer), which contains two kinds of +renderers: -\dot -digraph G { - node [shape=record, fontname=Helvetica, fontsize=10]; - edge [arrowhead="open", dir="both", arrowtail="none", - labelfontname=Helvetica, labelfontsize=10, color="#404040", - labelfontcolor="#000080"]; - fontname=Helvetica; fontsize=10; - - "background renderer (as a part of style)" -> "image buffer" [headlabel="*", - taillabel="1"]; - "widget (or a part of it)" -> "background renderer (as a part of style)" - [headlabel="*", taillabel="1"]; -} -\enddot - -Unlike dw::Image, dw::core::style::BgRenderer is not associated with a -certain rectangle on the canvas. Instead, widgets, or parts of widgets -take this role. This is generally represented by an implementation of -the interface dw::core::style::BgAllocation, which is implemented by -dw::core::Widget, but also by all parts of widget implementation, -which may have an own background image. +- one instance of dw::core::style::StyleImage::StyleImgRenderer, which + does everything needed for dw::core::style::StyleImage, and +- other renderers, used externally (widgets etc.), which are added by + dw::core::style::StyleImage::putExternalImgRenderer (and removed by + dw::core::style::StyleImage::removeExternalImgRenderer). -The following diagram gives a total overview: +This diagram gives an comprehensive overview: \dot digraph G { @@ -79,70 +92,144 @@ digraph G { labelfontcolor="#000080"]; fontname=Helvetica; fontsize=10; - "DICache Entry"; - - subgraph cluster_dw_images { + subgraph cluster_dw_style { style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10; - label="Dw Images"; - ImageRenderer [URL="\ref dw::core::ImageRenderer", color="#ff8080"]; - Imgbuf [URL="\ref dw::core::Imgbuf", color="#ff8080"]; + Style [URL="\ref dw::core::style::Style"]; + StyleImage [URL="\ref dw::core::style::StyleImage"]; + Imgbuf [URL="\ref dw::core::Imgbuf", color="#a0a0a0"]; + StyleImgRenderer + [URL="\ref dw::core::style::StyleImage::StyleImgRenderer"]; + ImgRenderer [URL="\ref dw::core::ImgRenderer", color="#ff8080"]; + ImgRendererDist [URL="\ref dw::core::ImgRendererDist"]; + ExternalImgRenderer + [URL="\ref dw::core::style::StyleImage::ExternalImgRenderer", + color="#a0a0a0"]; + ExternalWidgetImgRenderer + [URL="\ref dw::core::style::StyleImage::ExternalWidgetImgRenderer", + color="#a0a0a0"]; } - subgraph cluster_widgets { + subgraph cluster_dw_layout { style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10; - label="Widgets"; - Widget [URL="\ref dw::core::Widget", color="#a0a0a0"]; - Textblock [URL="\ref dw::Textblock"]; - "Textblock::Word" [URL="\ref dw::Textblock::Word"]; - Table [URL="\ref dw::Table"]; - "Table::Row" [URL="\ref dw::Table::Row"]; - Image [URL="\ref dw::Image"]; + Layout [URL="\ref dw::core::Layout"]; + LayoutImgRenderer [URL="\ref dw::core::Layout::LayoutImgRenderer"]; } - subgraph cluster_style { + subgraph cluster_dw_widget { style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10; - label="dw::core::style"; - Style [URL="\ref dw::core::style::Style"]; - BgRenderer [URL="\ref dw::core::style::BgRenderer"]; - BgAllocation [URL="\ref dw::core::style::BgAllocation", color="#ff8080"]; + Widget [URL="\ref dw::core::Widget", color="#a0a0a0"]; + WidgetImgRenderer [URL="\ref dw::core::Widget::WidgetImgRenderer"]; } - "DICache Entry" -> ImageRenderer [headlabel="*", taillabel="1"]; - "DICache Entry" -> Imgbuf [headlabel="1", taillabel="1"]; - - BgRenderer -> Imgbuf [headlabel="1", taillabel="*"]; - BgRenderer -> BgAllocation [headlabel="*", taillabel="1"]; - ImageRenderer -> BgRenderer [arrowhead="none", arrowtail="empty", dir="both", - style="dashed"]; - ImageRenderer -> Image [arrowhead="none", arrowtail="empty", dir="both", - style="dashed"]; - - Style -> BgRenderer [headlabel="0..1", taillabel="1"]; + subgraph cluster_dw_textblock { + style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10; - Widget -> Textblock [arrowhead="none", arrowtail="empty", dir="both"]; - Textblock -> "Textblock::Word" [headlabel="*", taillabel="1"]; - Widget -> Table [arrowhead="none", arrowtail="empty", dir="both"]; - Table -> "Table::Row" [headlabel="*", taillabel="1"]; - Widget -> Image [arrowhead="none", arrowtail="empty", dir="both"]; + Textblock [URL="\ref dw::Textblock"]; + Word [URL="\ref dw::Textblock::Word"]; + WordImgRenderer [URL="\ref dw::Textblock::WordImgRenderer"]; + SpaceImgRenderer [URL="\ref dw::Textblock::SpaceImgRenderer"]; + } - BgAllocation -> Widget [arrowhead="none", arrowtail="empty", dir="both", - style="dashed"]; - BgAllocation -> "Textblock::Word" [arrowhead="none", arrowtail="empty", + Style -> StyleImage [headlabel="*", taillabel="1"]; + StyleImage -> Imgbuf [headlabel="*", taillabel="1"]; + StyleImage -> StyleImgRenderer [headlabel="1", taillabel="1"]; + StyleImage -> ImgRendererDist [headlabel="1", taillabel="1"]; + ImgRendererDist -> StyleImgRenderer [headlabel="1", taillabel="1"]; + ImgRendererDist -> ImgRenderer [headlabel="1", taillabel="*"]; + + ImgRenderer -> ImgRendererDist [arrowhead="none", arrowtail="empty", + dir="both", style="dashed"]; + ImgRenderer -> StyleImgRenderer [arrowhead="none", arrowtail="empty", + dir="both", style="dashed"]; + ImgRenderer -> ExternalImgRenderer [arrowhead="none", arrowtail="empty", dir="both", style="dashed"]; - BgAllocation -> "Table::Row" [arrowhead="none", arrowtail="empty", - dir="both", style="dashed"]; + ExternalImgRenderer -> ExternalWidgetImgRenderer [arrowhead="none", + arrowtail="empty", dir="both", style="dashed"]; + + Layout -> LayoutImgRenderer [headlabel="1", taillabel="0..1"]; + ExternalImgRenderer -> LayoutImgRenderer [arrowhead="none", + arrowtail="empty", dir="both", style="dashed"]; + + Widget -> WidgetImgRenderer [headlabel="1", taillabel="0..1"]; + ExternalWidgetImgRenderer -> WidgetImgRenderer [arrowhead="none", + arrowtail="empty", dir="both", style="dashed"]; + + Textblock -> Word [headlabel="1", taillabel="*"]; + Word -> WordImgRenderer [headlabel="1", taillabel="0..1"]; + Word -> SpaceImgRenderer [headlabel="1", taillabel="0..1"]; + ExternalWidgetImgRenderer -> WordImgRenderer [arrowhead="none", + arrowtail="empty", dir="both", style="dashed"]; + WordImgRenderer -> SpaceImgRenderer [arrowhead="none", arrowtail="empty", + dir="both", style="dashed"]; } \enddot <center>[\ref uml-legend "legend"]</center> -<h2>Integration into dillo</h2> +Memory management +----------------- + +dw::core::style::StyleImage extends lout::signal::ObservedObject, so +that deleting this instance can be connected to code dealing with +cache clients etc. See StyleImageDeletionReceiver and how it is +attached in StyleEngine::apply ("case CSS_PROPERTY_BACKGROUND_IMAGE"). + + +Bugs and Things Needing Improvement +=================================== + +(Mostly related to image backgrounds, when not otherwise mentioned.) + +High Priority +------------- + +**Configurability, security/privacy aspects, etc.,** which are +currently available for image widgets, should be adopted. Perhaps some +more configuration options specially for background images. + + +Medium Priority +--------------- + +**Background-attachment** is not yet implemented, and will be postponed. + +**Calls to dw::core::ImgRenderer::fatal** are incomplete. As an +example, it is not called, when connecting to a server fails. (And so, +as far as I see, no cache client is started.) + + +Low Priority +------------ + +**Alpha support:** (not related to image backgrounds) currently alpha +support (and also colormap management) is done in dicache, while +dw::Image is only created with type RGB. This leads to several problems: + +- One dicache entry (representing an image related to the same URL), + which has only one background color, may refer to different images + with different background colors. +- The dicache only handles background colors, not background images. + +The solution is basicly simple: keep alpha support out of dicache; +instead implement RGBA in dw::Image. As it seems, the main problem is +alpha support in FLTK/X11. + + +Solved (Must Be Documented) +--------------------------- -\todo Add some references. +*Drawing background images row by row may become slow. As an +alternative, dw::core::ImgRenderer::finish could be used. However, +drawing row by row could become an option.* There is now +dw::core::style::drawBackgroundLineByLine, which can be changed in the +code, and is set to *false*. The old code still exists, so changing +this to *true* activates again drawing line by line. +(For image widgets, this could also become an option: in contexts, +when image data is retrieved in a very fast way.) */ |