NetSurf
image_cache.h
Go to the documentation of this file.
1/*
2 * Copyright 2011 John-Mark Bell <jmb@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/** \file
20 * The image content handler intermediate image cache.
21 *
22 * This cache allows netsurf to use a generic intermediate bitmap
23 * format without keeping the
24 * intermediate representation in memory.
25 *
26 * The bitmap structure is opaque to the rest of netsurf and is
27 * controlled by the platform-specific code (see image/bitmap.h for
28 * detials). All image content handlers convert into this format and
29 * pass it to the plot functions for display,
30 *
31 * This cache maintains a link between the underlying original content
32 * and the intermediate representation. It is intended to be flexable
33 * and either manage the bitmap plotting completely or give the image
34 * content handler complete control.
35 */
36
37#ifndef NETSURF_IMAGE_IMAGE_CACHE_H_
38#define NETSURF_IMAGE_IMAGE_CACHE_H_
39
40#include "utils/errors.h"
42
43struct content;
45struct redraw_context;
46
47typedef struct bitmap * (image_cache_convert_fn) (struct content *content);
48
50 /** How frequently the background cache clean process is run (ms) */
51 unsigned int bg_clean_time;
52
53 /** The target upper bound for the image cache size */
54 size_t limit;
55
56 /** The hysteresis allowed round the target size */
57 size_t hysteresis;
58
59 /** The speculative conversion "small" size */
61};
62
63/** Initialise the image cache
64 *
65 * @param image_cache_parameters The control parameters for the image cache
66 */
69
70/** adds an image content to be cached.
71 *
72 * @param content The content handle used as a key
73 * @param bitmap A bitmap representing the already converted content or NULL.
74 * @param convert A function pointer to convert the content into a bitmap or NULL.
75 * @return A netsurf error code.
76 */
78 struct bitmap *bitmap,
79 image_cache_convert_fn *convert);
80
82
83
84/** Obtain a bitmap from a content converting from source if neccessary. */
85struct bitmap *image_cache_get_bitmap(const struct content *c);
86
87/** Obtain a bitmap from a content with no conversion */
88struct bitmap *image_cache_find_bitmap(struct content *c);
89
90/** Decide if a content should be speculatively converted.
91 *
92 * This allows for image content handlers to ask the cache if a bitmap
93 * should be generated before it is added to the cache. This is the
94 * same decision logic used to decide to perform an immediate
95 * conversion when a content is initially added to the cache.
96 *
97 * @param c The content to be considered.
98 * @return true if a speculative conversion is desired false otherwise.
99 */
100bool image_cache_speculate(struct content *c);
101
102/**
103 * Fill a buffer with information about a cache entry using a format.
104 *
105 * The format string is copied into the output buffer with the
106 * following replaced:
107 * %e - The entry number
108 * %k - The content key
109 * %r - The number of redraws of this bitmap
110 * %c - The number of times this bitmap has been converted
111 * %s - The size of the current bitmap allocation
112 *
113 * \param string The buffer in which to place the results.
114 * \param size The size of the string buffer.
115 * \param entryn The opaque entry number.
116 * \param fmt The format string.
117 * \return The number of bytes written to \a string or -1 on error
118 */
119int image_cache_snentryf(char *string, size_t size, unsigned int entryn,
120 const char *fmt);
121
122/**
123 * Fill a buffer with information about the image cache using a format.
124 *
125 * The format string is copied into the output buffer with the
126 * following replaced:
127 *
128 * a Configured cache limit size
129 * b Configured cache hysteresis size
130 * c Current caches total consumed size
131 * d Number of images currently in the cache
132 * e The age of the cache
133 * f The largest amount of space the cache has occupied since initialisation
134 * g The number of objetcs when the cache was at its largest
135 * h The largest number of images in the cache since initialisation
136 * i The size of the cache when the largest number of objects occoured
137 * j The total number of read operations performed on the cache
138 * k The total number of read operations satisfied from the cache without
139 * conversion.
140 * l The total number of read operations satisfied from the cache which
141 * required a conversion.
142 * m The total number of read operations which could not be sucessfully
143 * returned. ie. not available in cache and conversion failed.
144 * n The total size of read operations performed on the cache
145 * o The total size of read operations satisfied from the cache without
146 * conversion.
147 * q The total size of read operations satisfied from the cache which
148 * required a conversion.
149 * r The total size of read operations which could not be sucessfully
150 * returned. ie. not available in cache and conversion failed.
151 * s The number of images which were placed in the cache but never read.
152 * t The number of images that were converted on insertion into the cache which were subsequently never used.
153 * u The number of times an image was converted after the first
154 * v The number of images that had extra conversions performed.
155 * w Size of the image that was converted (read missed cache) highest number
156 * of times.
157 * x The number of times the image that was converted (read missed cache)
158 * highest number of times.
159 *
160 * format modifiers:
161 * A p before the value modifies the replacement to be a percentage.
162 *
163 *
164 * \param string The buffer in which to place the results.
165 * \param size The size of the string buffer.
166 * \param fmt The format string.
167 * \return The number of bytes written to \a string or -1 on error
168 */
169
170int image_cache_snsummaryf(char *string, size_t size, const char *fmt);
171
172/********* Image content handler generic cache callbacks ************/
173
174/**
175 * Generic content redraw callback
176 *
177 * May be used by image content handlers as their redraw
178 * callback. Performs all neccissary cache lookups and conversions and
179 * calls the bitmap plot function in the redraw context.
180 */
181bool image_cache_redraw(struct content *c,
182 struct content_redraw_data *data,
183 const struct rect *clip,
184 const struct redraw_context *ctx);
185
186void image_cache_destroy(struct content *c);
187
188void *image_cache_get_internal(const struct content *c, void *context);
189
190bool image_cache_is_opaque(struct content *c);
191
193
194#endif
Declaration of content enumerations.
content_type
The type of a content.
Definition: content_type.h:53
Error codes.
nserror
Enumeration of error codes.
Definition: errors.h:29
struct bitmap *() image_cache_convert_fn(struct content *content)
Definition: image_cache.h:47
struct bitmap * image_cache_get_bitmap(const struct content *c)
Obtain a bitmap from a content converting from source if neccessary.
Definition: image_cache.c:346
content_type image_cache_content_type(void)
Definition: image_cache.c:873
void * image_cache_get_internal(const struct content *c, void *context)
Definition: image_cache.c:856
void image_cache_destroy(struct content *c)
Definition: image_cache.c:841
nserror image_cache_remove(struct content *content)
Definition: image_cache.c:567
bool image_cache_redraw(struct content *c, struct content_redraw_data *data, const struct rect *clip, const struct redraw_context *ctx)
Generic content redraw callback.
Definition: image_cache.c:798
bool image_cache_speculate(struct content *c)
Decide if a content should be speculatively converted.
Definition: image_cache.c:377
int image_cache_snentryf(char *string, size_t size, unsigned int entryn, const char *fmt)
Fill a buffer with information about a cache entry using a format.
Definition: image_cache.c:692
nserror image_cache_add(struct content *content, struct bitmap *bitmap, image_cache_convert_fn *convert)
adds an image content to be cached.
Definition: image_cache.c:510
struct bitmap * image_cache_find_bitmap(struct content *c)
Obtain a bitmap from a content with no conversion.
Definition: image_cache.c:402
nserror image_cache_fini(void)
Definition: image_cache.c:438
bool image_cache_is_opaque(struct content *c)
Definition: image_cache.c:862
int image_cache_snsummaryf(char *string, size_t size, const char *fmt)
Fill a buffer with information about the image cache using a format.
Definition: image_cache.c:585
nserror image_cache_init(const struct image_cache_parameters *image_cache_parameters)
Initialise the image cache.
Definition: image_cache.c:416
RISC OS wimp toolkit bitmap.
Definition: bitmap.c:68
uint32 size
Definition: bitmap.c:73
parameters to content redraw
Definition: content.h:40
Content which corresponds to a single URL.
size_t speculative_small
The speculative conversion "small" size.
Definition: image_cache.h:60
unsigned int bg_clean_time
How frequently the background cache clean process is run (ms)
Definition: image_cache.h:51
size_t limit
The target upper bound for the image cache size.
Definition: image_cache.h:54
size_t hysteresis
The hysteresis allowed round the target size.
Definition: image_cache.h:57
Rectangle coordinates.
Definition: types.h:40
Redraw context.
Definition: plotters.h:51
static nserror clip(const struct redraw_context *ctx, const struct rect *clip)
Sets a clip rectangle for subsequent plot operations.
Definition: plot.c:357