Opera 12.15 Source Code
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

image.h 58KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458
  1. /* -*- Mode: c++; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*-
  2. **
  3. ** Copyright (C) 1995-2007 Opera Software AS. All rights reserved.
  4. **
  5. ** This file is part of the Opera web browser.
  6. ** It may not be distributed under any circumstances.
  7. */
  8. /** @mainpage img
  9. The img module is responsible for the following:
  10. <ol>
  11. <li>Decode images.
  12. <li>Cache images.
  13. <li>Information about images, so that other parts of the code (like
  14. the display module) can use this information to draw an image,
  15. or to format a page according to the size of the image.
  16. </ol>
  17. A number of image formats is available in the img module. See
  18. ImageDecoderFactory for more information about the image formats.
  19. The img module is rather independent of the rest of the modules.
  20. The img module <b>depends on</b>:
  21. <ul>
  22. <li>libjpeg or jaypeg
  23. <li>minpng
  24. <li>pi
  25. <li>util
  26. </ul>
  27. The img module <b>is used by</b>:
  28. <ul>
  29. <li>display
  30. <li>doc
  31. <li>dochand
  32. <li>hardcore
  33. <li>layout
  34. <li>logdoc
  35. <li>skin
  36. <li>style
  37. <li>url
  38. <li>windowcommander
  39. <li>adjunct/quick
  40. </ul>
  41. <h3>What about image drawing?</h3>
  42. The img module is not responsible for drawing images. You can ask
  43. for an OpBitmap for an Image from the img module, and other code
  44. (the display module) will be responsible for drawing the actual image.
  45. The img module can also create tiled bitmaps and effect bitmaps
  46. on request from code responsible for image drawing.
  47. One important thing to know is that the img module is a little
  48. bit more complex than it would need to be, since it supports
  49. both images used in a web page, and images used in the user
  50. interface.
  51. <h3>What about animation?</h3>
  52. The img module is not responsible for the actual animation. The img
  53. module knows nothing about timers. However, there are a number of
  54. functions for the code that does the actual animation, that the
  55. img module provide. Image::IsAnimated(), Image::GetCurrentFrameDuration(),
  56. Image::GetCurrentFrameRect(), Image::Animate().
  57. <h3>Which features can I use?</h3>
  58. The most advanced feature for the img module is the
  59. FEATURE_ASYNC_IMAGE_DECODERS. It will enable the use
  60. of asynchronous img decoders, that is, decoders that
  61. we will get a callback for later if they have finished decoding,
  62. and not directly, when the call to ImageDecoder::DecodeData()
  63. has returned.
  64. FEATURE_ASYNC_IMAGE_DECODERS is only used on the Symbian platform,
  65. to be able to integrate with the Symbian media server. We have
  66. also a define, ASYNC_IMAGE_DECODERS_EMULATION, which can be used
  67. to emulate asynchronous decoders with our own decoders. We need
  68. this to be able to do debugging on other platforms than Symbian,
  69. with better tools.
  70. FEATURE_INTERNAL_IMAGE_DECODERS is normally used, but is not used
  71. for the Symbian platform. If this one is defined, the decoders
  72. in the img module will be compiled and used.
  73. FEATURE_LIBPNG will use the libpng instead of minpng. I recommend
  74. that you do not use libpng, it will be deprecated soon.
  75. FEATURE_SYSTEM_JPG will use the system's libjpeg implementation
  76. instead of one that we compile ourselves. Will save footprint,
  77. but you may get unpleasent bugs. Have this in mind if you turn
  78. this feature on.
  79. FEATURE_INDEXED_OPBITMAP will use indexed 8-bit bitmaps when
  80. it is possible. If this feature is not used, all bitmaps
  81. will be 32 bits.
  82. Then we have all the image format features, FEATURE_JPG, FEATURE_PNG,
  83. FEATURE_BMP, FEATURE_WBMP, FEATURE_XBM, and FEATURE_ICO. There is
  84. no feature for gif, we expect gif decoding to always be available.
  85. Notice that you will need to turn this features on, if you want
  86. to support an image format, even if you are not using internal
  87. image decoders. Other modules depend on these features. Also
  88. note that the targa (tga) decoder is only used for testing purposes.
  89. It is not included in release builds, and is not planned to be
  90. a part of the release of dali_3.
  91. <h3>How can I adapt the img module to my needs?</h3>
  92. First of all, you can use all the features above. Then, you
  93. can initialize the img module with the right set of decoders.
  94. You can also, at any time, change cache size and cache policy
  95. with ImageManager::SetCacheSize(). When memory is low,
  96. ImageManager::FreeMemory() can be called, which will free up
  97. as much memory as possible.
  98. <h3>How do I initialize the img module?</h3>
  99. <ol>
  100. <li>Call ImageManager::Create(), and set the imgManager variable
  101. to the ImageManager returned by this function. Send in an
  102. ImageProgressListener (may not be NULL). We need the
  103. ImageProgessListener to be able to take a break in the decoding
  104. of an image, and just say that we want to continue decoding
  105. later. This is to make sure that tasks with higher priorities
  106. (like ui response) will not be delayed.
  107. <li>Call ImageManager::AddImageDecoderFactory() for each image format
  108. that you want to support. The ImageDecoderFactory will be deleted
  109. when the imgManager is deleted, thus the ownership of the
  110. ImageDecoderFactory is passed from the caller to the ImageManager.
  111. You can add an ImageDecoderFactory provided by the img module,
  112. or an ImageDecoderFactory implemented elsewhere.
  113. <li>Call ImageManager::SetCacheSize() to set the cache size
  114. and the cache policy.
  115. </ol>
  116. <h3>How do I free the img module?</h3>
  117. <ol>
  118. <li>Make sure that no Image objects are visible.
  119. <li>Make sure that no Image objects are referenced from outside the
  120. img module.
  121. <li>delete imgManager and set imgManager=NULL.
  122. </ol>
  123. If you forget to free the img module, a lot of memory will be leaked,
  124. in the worst case a lot more than the image cache size, because of
  125. the cache policy used.
  126. <h3>What about stack memory usage?</h3>
  127. The img module does not consume a lot of stack. It is not recursive,
  128. and it has not very deep call chains. However, it is calling libjpeg/jaypeg
  129. and minpng modules, so it depends on the stack depth of those modules.
  130. <h3>What about heap memory usage?</h3>
  131. The img module uses a lot of heap memory.
  132. All referenced images have a little object (max 32 bytes each). There can be
  133. lot of images with a reference, since all documents with an image in them
  134. will reference an image in the img module. Thus, this is a O(n) issue. If we
  135. have a lot of documents with a lot of images, this may take up a lot of
  136. memory. However, it is not likely to be a problem, since the document will
  137. use much more memory than the referenced image. It is not possible to
  138. set an hard upper limit on the number of referenced images, so it is
  139. a little bit dangerous.
  140. Then we have representations of decoded images (bitmaps). They will use
  141. much more memory than the referenced images (width * height * bytes_per_pixel
  142. + constant_amount_of_info_bytes). The constant_amount_of_info_bytes is not
  143. included in the cache size right now, but the rest of the data is.
  144. With the right cache policy, we would never use more memory for the decoded
  145. images than the specified cache size. However, we always keep visible images
  146. decoded in memory. There can be a lot of visible documents at once, so the
  147. cache size has nothing to do with how much memory is used. I would like to
  148. implement a strict cache, but that will need changes in the document code.
  149. The document code is always expecting all inline urls to be loaded into
  150. memory as long as the document is visible/active.
  151. For animated images, we keep decoded images for each frame, plus sometimes
  152. also the combined image of all frames up to a certain point (important
  153. speed-up). This combined image is in 32 bit format, so it will use a lot of
  154. memory. Today, this implementation has not a very good and well defined
  155. cache strategy. Need to document better.
  156. Other memory used is listener objects, one for each document referencing
  157. to a specific image. They do not use much memory (around 16 bytes), but
  158. and is not bound by anything else than the current cached documents.
  159. The first implementation only had listeners for visible images, but it
  160. is possible that this has changed in the desktop optimization. Need to
  161. document better.
  162. During decoding, some more memory is used. There is no upper bound of
  163. the number of images decoding at the same time, but normally, it will
  164. not be that much. There is a special hack, and not very well documented,
  165. used for desktop, where both visible and invisible images is decoded at
  166. the same time.
  167. Depending on the decoder, more or less memory is used during decoding.
  168. See documentation for each ImageDecoder to find out how much.
  169. <h3>What about static memory usage?</h3>
  170. Two global variables exist in the img module, both are pointers
  171. to objects, both are created in ImageManager::Create() and deleted
  172. in ImageManager::~ImageManger(). They use very little memory.
  173. <h3>OOM handling</h3>
  174. The img module is using OP_STATUS internally. Mostly, it is also using
  175. OP_STATUS externally. However, since decoding can happen asynchronously,
  176. other oom strategies have been needed. ImageListener::OnError() is signalled
  177. when something (oom or decoding error) happens during decoding. Each
  178. document interested in the image will get called when the error happens.
  179. Then, it is also possible to call Image::IsOOM() to know if an image
  180. had an oom error. This one is only called from the VisualDevice in ImageOut,
  181. do not know if this one is needed. Need more documentation.
  182. OOM is not handled internally in the img module. However, the img module
  183. will never break internally because an oom, and thus is always oom safe.
  184. <h3>Is temp buffers used?</h3>
  185. No temp buffers are used. However, memory used during decoding could use
  186. some kind of temporary memory, if we get an API later for retrieving safe
  187. (not shared) temporary memory, for higher speed. It is in the decoders
  188. we may need that, the rest of the code is not using much temporary memory.
  189. <h3>Coverage</h3>
  190. Coverage information missing right now.
  191. <h3>Tests</h3>
  192. A lot of tests missing. There are tests for the gif decoder, but the rest
  193. of the code in the module has no selftests.
  194. <h3>How do I use the img module?</h3>
  195. First, you need to know how to initialize and free the img module. It is
  196. documented above.
  197. If you want to decode an image with the help of the img module, you will
  198. need to implement an ImageContentProvider, which will provide the img
  199. module with a stream of data. This is an abstraction so that th img
  200. module does not need to know anything about urls. The ImageContentProvider
  201. will tell the Image that there is more data available in the stream when
  202. that happens, and will call ImageContentProviderListener::OnMoreData()
  203. (reimplemented in Image). Since this is a kind of a stream interface,
  204. the img module will decide if it wants to read data or not when it is
  205. told that there are more data available through the ImageContentProvider.
  206. When you want to decode an Image, you should use ImageManager::GetImage()
  207. and send in the ImageContentProvider to your streamed data source. The img
  208. module will check if this object is already available, and return a reference
  209. to this Image, or create new Image data if this Image is already available.
  210. If the Image already was decoded, you will not need to decode the Image, which
  211. is a nice time saver.
  212. If you have an Image that will be visible on screen, you call
  213. Image::IncVisible() with an ImageListener as parameter. When
  214. it is not visible anymore, Image::DecVisible() should be called.
  215. Depending on the cache policy, Image::IncVisible() can trigger
  216. a decoding of the Image.
  217. If you want to reload an Image, first call ImageManager::ResetImage().
  218. with the right ImageContentProvider. That way,
  219. any information belonging to the Image, like the decoded bitmap and
  220. the size of the Image, will be cleared. Then of course you will
  221. need to trigger the decoding with ImageContentProviderListener::OnMoreData().
  222. <h3>Future plans for the img module</h3>
  223. There are no immediate changes in the pipe, however
  224. there are a few ideas for small changes.
  225. <ol>
  226. <li>Move atvef code outside the img module. It was discussed quite a bit
  227. before I accepted atvef code in the img module (I was against it, and
  228. still am). To do this in a good way, some of the doc code will need
  229. to be redesigned. Will discuss this with other module owners. Will
  230. not happen in core-2, maybe in core-3.
  231. <li>Handle error messages differently. Now, a lot of things is happening
  232. through callbacks in listeners, and it seems like it is a little
  233. too much of it going on, making the code a bit too hard to follow.
  234. <li>Create modules for all the img decoders. That way, less merging
  235. will be needed when bugs are fixed.
  236. <li>Support the mng format. We may need some redesign of the rest of
  237. the img module to be able to do that.
  238. <li>Get a better design for what is needed by the ui and what is needed
  239. by core in the img module.
  240. <li>Use better caching for tiles, animations, scaled bitmaps.
  241. <li>Scale bitmaps during decoding.
  242. <li>Be able to decode just parts of an image.
  243. <li>Support decoders (like the MHW decoder) that will need to scale
  244. the bitmap during decoding.
  245. <li>Implement a cache policy where visible images can be thrown out
  246. of the cache. We will need to redesign other code to be able to
  247. do that.
  248. <li>Implement a cache policy where images in an active document will
  249. be decoded even if they are not visible. This is already happening
  250. today, but it is a hack, and it isn't nice with memory usage (a
  251. desktop hack only good for newer desktop machines). In the planned
  252. improvement, only if we have enough room in the cache, we will
  253. decode non-visible images.
  254. <li>Make it possible to cache encoded images in memory, instead of caching
  255. decoded bitmaps.
  256. <li>Make it possible to RLE encode bitmaps, to have a faster format than
  257. other formats, but use less memory than bitmaps.
  258. <li>Make it possible to decode smaller parts of an image.
  259. <li>Make it possible to reload an image in one document, and still
  260. use the old representation of the image in another document.
  261. </ol>
  262. */
  263. #ifndef IMAGE_H
  264. #define IMAGE_H
  265. #include "modules/img/img_capabilities.h"
  266. #if defined(IMG_CACHE_UNUSED_IMAGES) || defined(IMG_TOGGLE_CACHE_UNUSED_IMAGES)
  267. # define CACHE_UNUSED_IMAGES
  268. #endif // IMG_CACHE_UNUSED_IMAGES || IMG_TOGGLE_CACHE_UNUSED_IMAGES
  269. class ImageRep;
  270. class OpBitmap;
  271. #ifdef CPUUSAGETRACKING
  272. class CPUUsageTracker;
  273. #endif // CPUUSAGETRACKING
  274. #ifdef ASYNC_IMAGE_DECODERS
  275. class AsyncImageDecoderFactory;
  276. #endif // ASYNC_IMAGE_DECODERS
  277. #ifdef CACHE_UNUSED_IMAGES
  278. #include "modules/url/url_id.h"
  279. #endif // CACHE_UNUSED_IMAGES
  280. /**
  281. * DisposalMethod is used to describe what happens after a frame has been displayed. Before the
  282. * first frame is added (even when we repeat the animation) all of the area of the image should be cleared.
  283. */
  284. enum DisposalMethod
  285. {
  286. /**
  287. * The frame should not be disposed, but left as is when we add the next frame.
  288. */
  289. DISPOSAL_METHOD_DO_NOT_DISPOSE = 1,
  290. /**
  291. * The rectangle that were covered with the frame should be cleared (the area will be transparent) before
  292. * we add next frame.
  293. */
  294. DISPOSAL_METHOD_RESTORE_BACKGROUND = 2,
  295. /**
  296. * The rectangle that were covered with the frame should be restored as it was before the frame was added,
  297. * before we add next frame.
  298. */
  299. DISPOSAL_METHOD_RESTORE_PREVIOUS = 3
  300. };
  301. #ifdef IMAGE_METADATA_SUPPORT
  302. /** ImageMetaData is used to identify different meta data values. Currently
  303. * they are only set from Jaypeg. */
  304. enum ImageMetaData
  305. {
  306. IMAGE_METADATA_ORIENTATION = 0,
  307. IMAGE_METADATA_DATETIME,
  308. IMAGE_METADATA_DESCRIPTION,
  309. IMAGE_METADATA_MAKE,
  310. IMAGE_METADATA_MODEL,
  311. IMAGE_METADATA_SOFTWARE,
  312. IMAGE_METADATA_ARTIST,
  313. IMAGE_METADATA_COPYRIGHT,
  314. IMAGE_METADATA_EXPOSURETIME,
  315. IMAGE_METADATA_FNUMBER,
  316. IMAGE_METADATA_EXPOSUREPROGRAM,
  317. IMAGE_METADATA_SPECTRALSENSITIVITY,
  318. IMAGE_METADATA_ISOSPEEDRATING,
  319. IMAGE_METADATA_SHUTTERSPEED,
  320. IMAGE_METADATA_APERTURE,
  321. IMAGE_METADATA_BRIGHTNESS,
  322. IMAGE_METADATA_EXPOSUREBIAS,
  323. IMAGE_METADATA_MAXAPERTURE,
  324. IMAGE_METADATA_SUBJECTDISTANCE,
  325. IMAGE_METADATA_METERINGMODE,
  326. IMAGE_METADATA_LIGHTSOURCE,
  327. IMAGE_METADATA_FLASH,
  328. IMAGE_METADATA_FOCALLENGTH,
  329. IMAGE_METADATA_SUBJECTAREA,
  330. IMAGE_METADATA_FLASHENERGY,
  331. IMAGE_METADATA_FOCALPLANEXRESOLUTION,
  332. IMAGE_METADATA_FOCALPLANEYRESOLUTION,
  333. IMAGE_METADATA_FOCALPLANERESOLUTIONUNIT,
  334. IMAGE_METADATA_SUBJECTLOCATION,
  335. IMAGE_METADATA_EXPOSUREINDEX,
  336. IMAGE_METADATA_SENSINGMETHOD,
  337. IMAGE_METADATA_CUSTOMRENDERED,
  338. IMAGE_METADATA_EXPOSUREMODE,
  339. IMAGE_METADATA_WHITEBALANCE,
  340. IMAGE_METADATA_DIGITALZOOMRATIO,
  341. IMAGE_METADATA_FOCALLENGTHIN35MMFILM,
  342. IMAGE_METADATA_SCENECAPTURETYPE,
  343. IMAGE_METADATA_GAINCONTROL,
  344. IMAGE_METADATA_CONTRAST,
  345. IMAGE_METADATA_SATURATION,
  346. IMAGE_METADATA_SHARPNESS,
  347. IMAGE_METADATA_SUBJECTDISTANCERANGE,
  348. IMAGE_METADATA_COUNT
  349. };
  350. #endif // IMAGE_METADATA_SUPPORT
  351. /**
  352. * ImageFrameData is a package for attributes for a frame in an image. It is used in
  353. * ImageDecoderListener::OnNewFrame, to avoid using lots of similar parameters to the
  354. * function (error prone, and probably also generates larger footprint or is slower).
  355. */
  356. struct ImageFrameData
  357. {
  358. /**
  359. * Default constructor, that will fill all of the attributes with 0 or FALSE, depending on the
  360. * type of each attricute. disposal_method will be set to DISPOSAL_METHOD_DO_NOT_DISPOSE.
  361. * @return a ImageFrameData with default values.
  362. */
  363. ImageFrameData() : interlaced(FALSE),
  364. transparent(FALSE),
  365. alpha(FALSE),
  366. duration(0),
  367. dont_blend_prev(FALSE),
  368. disposal_method(DISPOSAL_METHOD_DO_NOT_DISPOSE),
  369. bits_per_pixel(0),
  370. pal(NULL),
  371. pal_is_shared(FALSE),
  372. transparent_index(0),
  373. num_colors(0),
  374. bottom_to_top(FALSE)
  375. {
  376. }
  377. /**
  378. * The rectangle of the frame. This rectangle does not need to cover all of an image's total size.
  379. */
  380. OpRect rect;
  381. /**
  382. * TRUE if the frame data is interlaced, that is the data is not strictly given in a (0 -> (n -1),
  383. * where n is the number of lines) order, with line height 1 for each added line.
  384. */
  385. BOOL interlaced;
  386. /**
  387. * TRUE if this is a transparent frame, that is, an image where each pixel can be either opaque
  388. * or transparent.
  389. */
  390. BOOL transparent;
  391. /**
  392. * TRUE if this is a frame with alpha channels, where opaque level on each pixel can be between
  393. * 0 (totally transparent) to 255 (totally opaque).
  394. */
  395. BOOL alpha;
  396. /**
  397. * Nr of 1/100th:s of seconds this frame should be viewed, if this is an animated image (frame
  398. * nr at least a total of 2). If the complete image only consists of one frame, this value should
  399. * be ignored.
  400. */
  401. INT32 duration;
  402. /**
  403. * When combining a frame (after the first) in an animation, if TRUE, this frame will not be mixed
  404. * (using alpha/transparency) with the previous content in the canvas on the area it occupies, all
  405. * color values (including alpha/transparency) will simply be overwritten.
  406. */
  407. BOOL dont_blend_prev;
  408. /**
  409. * The disposal method for this frame. Only valid for animated images. See documentation of DisposalMethod.
  410. */
  411. DisposalMethod disposal_method;
  412. /**
  413. * Bits per pixel in the source data for the frame.
  414. */
  415. INT32 bits_per_pixel;
  416. /**
  417. * An array of palette entries(RGB, 3 bytes) if this is a index based image. If it is not index
  418. * based, this value will be NULL. The palette data is not valid after ImageDecoderListener::OnNewFrame()
  419. * has returned, so the listener will need to copy the data if it is interested in the data.
  420. */
  421. UINT8* pal;
  422. /**
  423. * Should be TRUE if it is known that the palette is shared for all frames (if there is several frames in the image).
  424. * FALSE if not, or if it is not known.
  425. */
  426. BOOL pal_is_shared;
  427. /**
  428. * The index value (0-255), that represents the index used to mark a pixel as transparent. This value only
  429. * has meaning if the transparent flag is TRUE, and we had a palette.
  430. */
  431. INT32 transparent_index;
  432. /**
  433. * The number of colors used in an indexed based image (1-255). If the image is not indexed based
  434. * (pal == NULL), this value has no meaning.
  435. */
  436. INT32 num_colors;
  437. BOOL bottom_to_top;
  438. };
  439. /**
  440. * Abstract class. The functions in this class
  441. * will be called from a decoder, when things
  442. * are happening there.
  443. */
  444. class ImageDecoderListener
  445. {
  446. public:
  447. virtual ~ImageDecoderListener() {}
  448. /**
  449. * Called when a line is decoded. Not normally called from asynchronous decoders. After the call, the
  450. * data given to the listener through this function is not valid, so the listener will have to copy the
  451. * data if it finds it interesting (which is the normal case).
  452. * @param data pointer to the data that represents the line. If the platform is supporting index based data, and the image can be represented with index based data, the data here will be in indexed data (one byte for each pixel). Otherwise, this data will be given in 32 bit format, BGRA on little endian and ARGB on big endian machines. This is because we want to be able to read an unsigned 32-bit number directly from the line data without, doing any conversion.
  453. * @param line the line in an image where we want the data to be placed. This line might be outside the specified image size, so you will have to clip all lines that does not fit into the image.
  454. * @param lineHeight the number of lines that should get the data given through this function, starting with line line. Normally this will be 1, the known exception is for gif images, where we for interlaced images want to write a line on several lines, to give the image the wanted interlaced effect. Since we will eventually add data to all lines, even when we have an interlaced image, the listener can choose to ignore to fill more than one line to save processor time.
  455. */
  456. virtual void OnLineDecoded(void* data, INT32 line, INT32 lineHeight) = 0;
  457. /**
  458. * Called when the total size of an image is known. An image can have a frame inside this total size that
  459. * does not cover everything. But that is just data, the real width and height of the image is the size
  460. * given here.
  461. * @return value is obsolete, you shouldn't use that. It will be removed in a later version of the img module.
  462. * @param width the total width of the image.
  463. * @param height the total height of the image.
  464. */
  465. virtual BOOL OnInitMainFrame(INT32 width, INT32 height) = 0;
  466. /**
  467. * Called when we have a new frame. When a new frame is started, all calls to OnLineDecoded belongs
  468. * to that frame (the new frame is the active frame). Before OnNewFrame has been called, OnLineDecoded
  469. * should not be called. For more documentation, see documentation of ImageFrameData.
  470. * @param image_frame_data the data describing the frame.
  471. */
  472. virtual void OnNewFrame(const ImageFrameData& image_frame_data) = 0;
  473. /**
  474. * Sets the number of times the animation will be played. A value of 0 means that it
  475. * will repeat forever. If this function is not called, you should assume that the
  476. * animation should be played once.
  477. * @param nrOfRepeats the number of times the animation will be played.
  478. */
  479. virtual void OnAnimationInfo(INT32 nrOfRepeats) = 0;
  480. /**
  481. * Called when all of the images has been decoded.
  482. */
  483. virtual void OnDecodingFinished() = 0;
  484. /**
  485. used when decoding asynchronously, to inform the listener that
  486. it should propagate that some progress has been made. will
  487. typically be called after a bunch of calls to OnLineDecoded, eg
  488. when the decoding thread yields. cannot be done from
  489. OnLineDecoded since this would cause too many invalidations.
  490. */
  491. virtual void ReportProgress() {}
  492. /**
  493. used when decoding asynchronously, to inform the listener that
  494. it should propagate that decoding failed.
  495. @param reason the reason decoding failed
  496. */
  497. virtual void ReportFailure(OP_STATUS reason) {}
  498. #ifdef IMAGE_METADATA_SUPPORT
  499. virtual void OnMetaData(ImageMetaData id, const char* data) = 0;
  500. #endif // IMAGE_METADATA_SUPPORT
  501. #ifdef EMBEDDED_ICC_SUPPORT
  502. /**
  503. * Called when data for an embedded ICC profile has been decoded.
  504. */
  505. virtual void OnICCProfileData(const UINT8* data, unsigned datalen) = 0;
  506. #endif // EMBEDDED_ICC_SUPPORT
  507. #ifdef ASYNC_IMAGE_DECODERS
  508. /**
  509. * The Symbian Image Converter outputs data directly to an
  510. * Epoc Specific bitmap, not line by line in RGBA format.
  511. * Hence the current bitmap need to be passed to the decoder.
  512. * @return, the current bitmap that the decoder should use.
  513. */
  514. virtual OpBitmap* GetCurrentBitmap() = 0;
  515. /**
  516. * Called when a portion (part) of the image has been decoded.
  517. */
  518. virtual void OnPortionDecoded() = 0;
  519. /**
  520. * Called when the decoder fails for some reason.
  521. * @param reason, OpStatus::ERR if this is a decoding error, OpStatus::ERR_NO_MEMORY if out of memory.
  522. */
  523. virtual void OnDecodingFailed(OP_STATUS reason) = 0;
  524. /**
  525. * This makes it possible for the decoder to query the content-type
  526. * of the image.
  527. */
  528. virtual INT32 GetContentType() = 0;
  529. /**
  530. * This makes it possible for the decoder to query the content-size
  531. * of the image.
  532. */
  533. virtual INT32 GetContentSize() = 0;
  534. #endif // ASYNC_IMAGE_DECODERS
  535. /**
  536. * This makes it possible for the listener to receive data without any colorspace conversion applied.
  537. */
  538. virtual BOOL IgnoreColorSpaceConversions() const { return FALSE; }
  539. };
  540. /**
  541. * Abstract class that we inherit to implement a decoder for a specific
  542. * format (gif, jpeg, png, etc).
  543. */
  544. class ImageDecoder
  545. {
  546. public:
  547. /**
  548. * Deletes the ImageDecoder object. The only way to restart a decoding is to delete the ImageDecoder object, and then
  549. * create a new one, sending in the data from the start of the image stream.
  550. */
  551. virtual ~ImageDecoder() {}
  552. /**
  553. * Decodes a chunk of an image. This function can be called several times.
  554. * @return OpStatus::ERR if decoding failed because of corrupt image, OpStatus::ERR_NO_MEMORY if out of memory while decoding.
  555. * @param data pointer to the data to be decoded.
  556. * @param numBytes number of bytes in the data to be decoded.
  557. * @param more TRUE if there potentially (but not necessarily) will be more data sent to the image decoder after this chunk of data.
  558. * @param resendBytes will contain the number of bytes which needs to be
  559. * sent as the start of the next chunk if the function returns OpStatus::OK. This is needed because some decoders are designed in such a way that some states cannot be saved inside the decoder, but will instead restart from a known safe position.
  560. * @param load_all if TRUE, someone has requested that the entire image should be loaded at once, if possible. does not necessarily mean that all data is available at this time - see Image::OnLoadAll.
  561. */
  562. virtual OP_STATUS DecodeData(const BYTE* data, INT32 numBytes, BOOL more, int& resendBytes, BOOL load_all = FALSE) = 0;
  563. /**
  564. * Sets the listener that is given information from the decoder.
  565. * @param imageDecoderListener will receive the information from the decoder.
  566. */
  567. virtual void SetImageDecoderListener(ImageDecoderListener* imageDecoderListener) = 0;
  568. };
  569. /**
  570. * ImageContentProvider is the source of the data given to images. We pull data from the
  571. * ImageContentProvider with GetData() when we are interested in more data.
  572. */
  573. class ImageContentProvider
  574. {
  575. public:
  576. /**
  577. * Deletes the content provider object.
  578. */
  579. virtual ~ImageContentProvider() {}
  580. /**
  581. * Is FALSE by default. Was needed to be able to compare two content providers, if they have
  582. * different implementation, it will not be possible to compare them with IsEqual(). The
  583. * reason that the return value is a BOOL, is that right now, in the current implementation,
  584. * we are only interested in sharing URL objects, ui images are not shared by several Image
  585. * objects. If that changed in the future, we will have to replace this function with one
  586. * returning an enumeration.
  587. * @return TRUE if this content provider got this data from a URL.
  588. */
  589. virtual BOOL IsUrlProvider() { return FALSE; }
  590. #ifdef CPUUSAGETRACKING
  591. /**
  592. * To properly blame the correct tab for the time spent in image decoding
  593. * an ImageContentProvider can implement this method and let it return
  594. * a pointer to an appropriate CPUUsageTracker. If this method
  595. * returns NULL, then the default ("Other") CPUUsageTracker will be used.
  596. *
  597. * This only applies for operations initiated by the image system itself,
  598. * such as non-synchronous decoding (ImageManager::Progress()). In other
  599. * cases the initiator of image operations have to decide what
  600. * CPUUsageTracker to blame.
  601. *
  602. * @return NULL or a pointer to a CPUUsageTracker.
  603. */
  604. virtual CPUUsageTracker* GetCPUUsageTracker() { return NULL; }
  605. #endif // CPUUSAGETRACKING
  606. /**
  607. * Gets a buffer with data from the content provider. The buffer will be valid until one of
  608. * ConsumeData(), Grow() or Reset() is called. Also, you should not keep a reference to the buffer for very long time.
  609. * @return OpStatus::ERR if no data was available at this time. OpStatus::ERR_NO_MEMORY if we ran out of memory while calling this function. If everthing is ok, and we got a buffer, OpStatus::OK will be returned.
  610. * @param buf will be set top point to the buffer with data from the content provider.
  611. * @param len will be set to the length of the buffer.
  612. * @param more will be set to TRUE if there is more data already loaded in the content provider. If there is not more data loaded after this buffer, or if all of the content provider's data has been loaded, more will be set to FALSE.
  613. */
  614. virtual OP_STATUS GetData(const char*& buf, INT32& len, BOOL& more) = 0;
  615. /**
  616. * Returns image type if it was known to the provider. This function will be called
  617. * if the regular image factories can not determine the type. It is intended for fallback
  618. * handling if everything else fails.
  619. *
  620. * @param data raw image data
  621. * @param len Length of data buffer in bytes
  622. */
  623. virtual INT32 CheckImageType(const UCHAR* data, INT32 len) { return -1; }
  624. /**
  625. * Grows the size of the buffer that will be returned in the next call to GetData(). This function
  626. * should only be called if GetData() returned TRUE in its more parameter the last time it was
  627. * called, so we know that the content provider has more data that can be used to grow the buffer
  628. * size. You are going to want to use this function when you have called ImageDecoder::DecodeData()
  629. * and the function returned a value equal to the size of the buffer sent to DecodeData().
  630. * @return OpStatus::ERR_NO_MEMORY if there is not enough memory to create a larger buffer, otherwise it will return OpStatus::OK.
  631. */
  632. virtual OP_STATUS Grow() = 0;
  633. /**
  634. * Consumes a number of bytes in the content provider, that is, moves the pointer in the data stream in
  635. * the content provider a number of bytes. You should call this function after a GetData() call, before
  636. * any call to Reset() or Grow(). You should not call this function with a value larger than the size of
  637. * the buffer returned by GetData().
  638. * @param len the number of bytes to consume.
  639. */
  640. virtual void ConsumeData(INT32 len) = 0;
  641. /**
  642. * @return the content type of the content provider's content.
  643. */
  644. virtual INT32 ContentType() = 0;
  645. #ifdef ASYNC_IMAGE_DECODERS
  646. /**
  647. * @return the content size of the content provider's content.
  648. */
  649. virtual INT32 ContentSize() = 0;
  650. #endif // ASYNC_IMAGE_DECODERS
  651. /**
  652. * Sets the content type of the content provider. This function will be called when someone finds out that
  653. * the content type of the content provider is wrong, and need to be updated to the correct value.
  654. * @param content_type the new content type for the content provider.
  655. */
  656. virtual void SetContentType(INT32 content_type) = 0;
  657. /**
  658. * Resets the content provider and if possible releases all buffers and other resources.
  659. */
  660. virtual void Reset() = 0;
  661. /**
  662. * Rewinds the content provider so that the next time that we call GetData, we will start reading from the beginning.
  663. * If possible, buffers and other resources are kept.
  664. */
  665. virtual void Rewind() = 0;
  666. /**
  667. * Compares two content providers, to see if they are using the same data stream.
  668. * @return TRUE if the content providers use the same data stream.
  669. * @param content_provider that we should compare this object with.
  670. */
  671. virtual BOOL IsEqual(ImageContentProvider* content_provider) = 0;
  672. /**
  673. * @return TRUE if all the content provider's content has been loaded from the network. Will always TRUE if the content provider is receiving its data from a synchronous source (disk or memory).
  674. */
  675. virtual BOOL IsLoaded() = 0;
  676. };
  677. /**
  678. * The ImageContentProviderListener is called by the corresponding ImageContentProvider. There is no
  679. * visible connection between the ImageContentProviderListener and the ImageContentProvider, except
  680. * for the parameter given to OnMoreData() and OnLoadAll().
  681. */
  682. class ImageContentProviderListener
  683. {
  684. public:
  685. /**
  686. * Deletes the content provider listener.
  687. */
  688. virtual ~ImageContentProviderListener() {}
  689. /**
  690. * Called when more data has arrived to the content provider. The listener can do whatever it wants
  691. * with this information. Error handling must be handled in a special way, since this function does
  692. * not have a return value.
  693. * @param content_provider the content provider that has more data.
  694. */
  695. virtual void OnMoreData(ImageContentProvider* content_provider) = 0;
  696. /**
  697. * Called to let the content provider listener that it should use all data at once from the content
  698. * provider. For an image, that means that all available data in the content provider should be decoded.
  699. * Note that animated images will only decode the first frame. After this call one
  700. * of IsDecoded(), IsAnimated() or IsFailed() will return TRUE.
  701. * @return OpStatus::ERR if decoding failed, OpStatus::ERR_NO_MEMORY or OpStatus::OK otherwise.
  702. * @param content_provider the content provider we are listening to.
  703. */
  704. virtual OP_STATUS OnLoadAll(ImageContentProvider* content_provider) = 0;
  705. };
  706. /**
  707. * An ImageListener listens to a specified image. An image can have several image listeners connected
  708. * to it. An ImageListener object is connected to an Image through the Image::IncVisible() call, and
  709. * disconnected through the Image::DecVisible() call.
  710. */
  711. class ImageListener
  712. {
  713. public:
  714. /**
  715. * Deletes the ImageListener.
  716. */
  717. virtual ~ImageListener() {}
  718. /**
  719. * Called when a portion of the image has been decoded.
  720. */
  721. virtual void OnPortionDecoded() = 0;
  722. /**
  723. * Called when there was an error while decoding the image that the ImageListener is connected to.
  724. * @param status OpStatus::ERR if decoding failed, OpStatus::ERR_NO_MEMORY if decoding failed because of we run out of memory.
  725. */
  726. virtual void OnError(OP_STATUS status) = 0;
  727. };
  728. /**
  729. * The NullImageListener has a singleton object called null_image_listener. It can be used in
  730. * Image::IncVisible() and Image::DecVisible() by everyone who isn't interested in error
  731. * reporting. The user interface is ising this when using ImageContentProviderListener::OnLoadAll(),
  732. * since the error messages are given as a return value then.
  733. */
  734. class NullImageListener : public ImageListener
  735. {
  736. public:
  737. void OnPortionDecoded() {}
  738. void OnError(OP_STATUS status) { OpStatus::Ignore(status); }
  739. };
  740. /**
  741. * An Image object is an object most often used on the stack. It shares ImageRep objects with other Image
  742. * objects. The ImageRep object is reference counted. Image objects with the same ImageContentProvider will
  743. * share the same ImageRep object.
  744. * We get an Image object from the ImageManager.
  745. */
  746. class Image : public ImageContentProviderListener
  747. {
  748. public:
  749. /**
  750. * An effect is a graphical operation that can be done on an image to change its appearance in a more or less
  751. * subtle way. The effect value given in Image::GetEffectBitmap() should be between 0 and 100. Effects are only
  752. * used for cool ui effects.
  753. * Effects can be combined, since we use a bit field.
  754. */
  755. enum Effect
  756. {
  757. /**
  758. * The image will look like it glows when this effect is applied. It becomes more yellow. The higher effect
  759. * value, the more the image will glow.
  760. */
  761. EFFECT_GLOW = 0x01,
  762. /**
  763. * This effect is not implemented or used. Should probably be removed.
  764. */
  765. EFFECT_COLORLESS = 0x02,
  766. /**
  767. * A disabled image will lose half of its opaque level, and thus will look more transparent. The effect
  768. * value has no effect.
  769. */
  770. EFFECT_DISABLED = 0x04,
  771. /**
  772. * Blends the background with this image, by reducing the opaque level in this image by a factor
  773. * effect_value / 100. A blend operation with effect value 50 is the same operation as the disabled effect.
  774. */
  775. EFFECT_BLEND = 0x08
  776. };
  777. Image();
  778. Image(const Image &image);
  779. ~Image();
  780. Image &operator=(const Image &image);
  781. /**
  782. * @return width of the image. Returns 0 if the width of the image is unknown or if the image contains an error before finding the width.
  783. */
  784. UINT32 Width() const;
  785. /**
  786. * @return height of the image. Returns 0 if the height of the image is unknown or if the image contains an error before finding the height.
  787. */
  788. UINT32 Height() const;
  789. /**
  790. * @return is this image not containing any data?
  791. */
  792. BOOL IsEmpty() const;
  793. /**
  794. * Empty() the image. (set rep to NULL)
  795. */
  796. void Empty() {SetImageRep(NULL);}
  797. /**
  798. * @return is all of the image has been successfully decoded?
  799. */
  800. BOOL ImageDecoded() const;
  801. /**
  802. * @return has this image any form of transparency? (transparent or alpha)
  803. */
  804. BOOL IsTransparent() const;
  805. /**
  806. * @return TRUE if the image does not get its data lines in normal order (0 -> height -1, one line at a time).
  807. */
  808. BOOL IsInterlaced() const;
  809. /**
  810. * Return TRUE if the content is believed relevant (interesting) to the user.
  811. * Basically, images with only one color (such as images used as spacers or backgroundcolors) would return FALSE.
  812. * All images return TRUE until all decoding is finished.
  813. */
  814. BOOL IsContentRelevant() const;
  815. /**
  816. * @return the last decoded line (line + 1). Will return Height() if ImageDecoded(). Will return 0 if no lines are decoded.
  817. */
  818. UINT32 GetLastDecodedLine() const;
  819. /**
  820. * When an image is made visible on screen, it should call IncVisible(). Only visible images will be decoded.
  821. * @return a status value of OpStatus::ERR_NO_MEMORY or OpStatus::OK.
  822. * @param image_listener is the ImageListener that is interested in this image.
  823. */
  824. OP_STATUS IncVisible(ImageListener* image_listener);
  825. /**
  826. * When an image is not visible on screen anymore, it should call DecVisible(). An image that is not visible at all should stop decoding. With some cache policies, the image representation might be deleteted immediately.
  827. * @param image_listener the ImageListener that is not interested in this image anymore.
  828. */
  829. void DecVisible(ImageListener* image_listener);
  830. /**
  831. * Try decode the image if there is free space in the memorycache. Does nothing if the image is visible.
  832. * PreDecoding images has lower priority than visible images.
  833. * PreDecoding images will not decoded while there is visible images to decode.
  834. * PreDecoding images will be removed from cache if a visible image needs the memory.
  835. */
  836. void PreDecode(ImageListener* image_listener);
  837. /**
  838. * DEBUG_PRIVATE: Counts the current image_listeners.
  839. */
  840. INT32 CountListeners();
  841. /**
  842. * DEBUG_PRIVATE: Get the reference count to this image.
  843. */
  844. INT32 GetRefCount();
  845. /**
  846. * MODULE_PRIVATE
  847. * Sets the ImageRep that this Image should represent.
  848. */
  849. void SetImageRep(ImageRep* imageRep);
  850. /**
  851. * COMMENT: Will not work for animated images?
  852. * @return the number of bits per pixel in the source image (that has nothing to do with the nr of pixels used in the actual image representation in memory).
  853. */
  854. int GetBitsPerPixel();
  855. /**
  856. * @return the number of frames in the source image. An image that is not animated has 1 frame. An image has 0 frames if not decoded or if it was something wrong with the decoding. If !ImageDecoded(), the return value from this function may not be accurate.
  857. */
  858. int GetFrameCount();
  859. /**
  860. * Syncronizes the animation accosiated with the dest_listener so that it will have the same loopnr and framenr as
  861. * the animation accosiated with source_listener.
  862. */
  863. void SyncronizeAnimation(ImageListener* dest_listener, ImageListener* source_listener);
  864. /**
  865. * Replaces the current bitmap in an Image that we got with ImageManager::GetImage(OpBitmap*).
  866. * @param new_bitmap the bitmap used to replace the current bitmap.
  867. * @return OpStatus::ERR_NO_MEMORY or OpStatus::OK
  868. */
  869. OP_STATUS ReplaceBitmap(OpBitmap* new_bitmap);
  870. /**
  871. * Will decode a part of the image, unless decoding this image has failed, image already decoded, or the image is not
  872. * visible. Will be called when there are more data available in the ImageContentProvider.
  873. * @param content_provider the ImageContentProvider that this Image gets its data from.
  874. */
  875. void OnMoreData(ImageContentProvider* content_provider);
  876. /**
  877. * Will decode all of this image, unless decoding this image has failed, image already decoded, or the image is
  878. * not visible. Only the first frame will be loaded in case of animated images, to avoid freeze for long animations.
  879. * Normally used for ui and javascript mouse over effects.
  880. * @return OpStatus::ERR if decoding error, otherwise OpStatus::ERR_NO_MEMORY or OpStatus::OK.
  881. * @param content_provider the ImageContentProvider that this Image gets its data from.
  882. */
  883. OP_STATUS OnLoadAll(ImageContentProvider* content_provider);
  884. /**
  885. * @return the offset of the image data inside the total image frame. Only used for single-frame images.
  886. */
  887. OpPoint GetBitmapOffset();
  888. /**
  889. * Gets an OpBitmap representing the image, and locks it into memory.
  890. * @return the bitmap with the data representation of the image. Will return NULL if there are no data in the image yet, or if there was an OOM condition.
  891. * @param image_listener the ImageListener that the returned bitmap will belong to. Needed because different image listeners may have different bitmap representations (only animated bitmaps can have different representations).
  892. */
  893. OpBitmap* GetBitmap(ImageListener* image_listener);
  894. /**
  895. * Releases the lock from the bitmap locked with GetBitmap(). If GetBitmap() returned NULL, this
  896. * function should not be called.
  897. */
  898. void ReleaseBitmap();
  899. /**
  900. * Gets a tiled representation of the image, and locks the bitmap into memory.
  901. * If the original bitmap is tiny, the image code will create and cache a larger (but not too large) bitmap and return that bitmap.
  902. * The desired_width and desired_height are used as a hint for the needed size of the tilebitmap (so it won't create a unnecessary large bitmap if you are only painting a small area anyway).
  903. * @return a OpBitmap with a tiled representation of the image. Will return NULL if there are no data in the image yet, or if there was an OOM condition.
  904. * @param image_listener the ImageListener that the returned bitmap will belong to. Needed because different image listeners may have different bitmap representations (only animated bitmaps can have different representations).
  905. * @param desired_width The width you are going to draw the tiled bitmap on.
  906. * @param desired_height The height you are going to draw the tiled bitmap on.
  907. */
  908. OpBitmap* GetTileBitmap(ImageListener* image_listener, int desired_width = 64, int desired_height = 64);
  909. /**
  910. * Releases the lock from the bitmap locked with GetTileBitmap(). If GetTileBitmap() returned NULL, this
  911. * function should not be called.
  912. */
  913. void ReleaseTileBitmap();
  914. /**
  915. * Gets an effect representation of the image, and locks the bitmap into memory. Used for ui effects.
  916. * @return a OpBitmap with an effect representation of the image. Will return NULL if there are no data in the image yet, or if there was an OOM condition.
  917. * @param effect the effect used on the original image representation, see Effect enumeration.
  918. * @param effect_value the value given to the effect, see documentation of Effect enumeration.
  919. */
  920. OpBitmap* GetEffectBitmap(INT32 effect, INT32 effect_value, ImageListener* image_listener = NULL);
  921. /**
  922. * Releases the lock from the bitmap locked with GetEffectBitmap(). If GetEffectBitmap() returned NULL, this
  923. * function should not be called.
  924. */
  925. void ReleaseEffectBitmap();
  926. /**
  927. * Gets a tiled effect representation of the image, and locks the bitmap into memory. Used for ui effects.
  928. * @return a OpBitmap with a tiled effect representation of the image. Will return NULL if there are no data in the image yet, or if there was an OOM condition.
  929. * @param effect the effect used on the original image representation, see Effect enumeration.
  930. * @param effect_value the value given to the effect, see documentation of Effect enumeration.
  931. * @param horizontal_count the number of times the image representation should be duplicated horizontally.
  932. * @param vertical_count the number of times the image representation should be duplicated vertically.
  933. */
  934. OpBitmap* GetTileEffectBitmap(INT32 effect, INT32 effect_value, int horizontal_count, int vertical_count);
  935. /**
  936. * Releases the lock from the bitmap locked with GetTileEffectBitmap(). If GetTileEffectBitmap() returned NULL, this
  937. * function should not be called.
  938. */
  939. void ReleaseTileEffectBitmap();
  940. /**
  941. * Checks if the image is known to be animated. This will only
  942. * return TRUE once we've found a second frame in the image
  943. * so it's also a sign that the first frame is decoded.
  944. *
  945. * @return TRUE if it is known that this is an animated image.
  946. */
  947. BOOL IsAnimated();
  948. /**
  949. * COMMENT: Need to discuss documentation with Emil.
  950. * Gets the duration of the current frame for a specific animated image.
  951. * @return the duration of the current image frame given in 1/100th:s of a second. Will return -1 if this is the last frame to be displayed infinitely.
  952. * @param image_listener the ImageListener that has a specific current image frame.
  953. */
  954. INT32 GetCurrentFrameDuration(ImageListener* image_listener);
  955. /**
  956. * COMMENT: Need to discuss documentation with Emil.
  957. * Gets the area that needs to be updated in an image, when a new frame should be displayed.
  958. * @return the area in the image that needs to be updated.
  959. * @param image_listener the ImageListener with a specific current image frame.
  960. */
  961. OpRect GetCurrentFrameRect(ImageListener* image_listener);
  962. /**
  963. * COMMENT: Need to discuss documentation with Emil.
  964. * Replaces the frame that the animated image points to, to the following frame.
  965. * @return TRUE if the frame was changed. Will not change frame if next frame is missing, or if the animation should not loop anymore.
  966. * @param image_listener the ImageListener that has its own position in the animation.
  967. */
  968. BOOL Animate(ImageListener* image_listener);
  969. /**
  970. * Resets animation's loop of an image having finite loop
  971. * @param image_listener the ImageListener that has its own position in the animation.
  972. */
  973. void ResetAnimation(ImageListener* image_listener);
  974. /**
  975. * Peeks the imagedimensions if they aren't known already. This doesn't load the image, it just tries to find the dimensions if there is enough data.
  976. */
  977. void PeekImageDimension();
  978. BOOL IsFailed();
  979. /**
  980. * Normally, images decode their data with the top line first, but sometimes
  981. * the decoding is the opposite (bmp). Ask this function how the data is decoded.
  982. * @return TRUE if this image is decoded with the bottom line first.
  983. */
  984. BOOL IsBottomToTop();
  985. /**
  986. * Call this function instead of GetLastDecodedLine() if IsBottomToTop() returns TRUE.
  987. * @return the lowest decoded line in the image. Everything below this line, including
  988. * the line, can be drawn to screen, the rest of the data is uninitialized, and should
  989. * not be drawn to screen (garbage).
  990. */
  991. UINT32 GetLowestDecodedLine();
  992. #ifdef IMG_GET_AVERAGE_COLOR
  993. /**
  994. * Get the average pixel color of the image.
  995. * @param image_listener the ImageListener that has its own position in the animation.
  996. */
  997. COLORREF GetAverageColor(ImageListener* image_listener);
  998. #endif // IMG_GET_AVERAGE_COLOR
  999. #ifdef HAS_ATVEF_SUPPORT
  1000. /**
  1001. * @return TRUE if this is an atvef image. Only used as a hack to help the atvef implementation.
  1002. */
  1003. BOOL IsAtvefImage();
  1004. #endif
  1005. BOOL operator==(const Image &image) {return image_rep == image.image_rep;}
  1006. BOOL operator!=(const Image &image) {return image_rep != image.image_rep;}
  1007. BOOL IsOOM();
  1008. #ifdef IMAGE_METADATA_SUPPORT
  1009. char* GetMetaData(ImageMetaData id);
  1010. BOOL HasMetaData();
  1011. #endif // IMAGE_METADATA_SUPPORT
  1012. private:
  1013. void IncRefCount();
  1014. void DecRefCount();
  1015. ImageRep* image_rep;
  1016. };
  1017. /**
  1018. * The ImageManager has normally an ImageProgressListener. The ImageProgressListener is used to report
  1019. * that the image code has decoded some of its data, and want to continue doing that, but do not want
  1020. * to lock up the user interface. ImageProgressListener::OnProgress() may not, when it is called, make
  1021. * a call back to the image code.
  1022. */
  1023. class ImageProgressListener
  1024. {
  1025. public:
  1026. virtual ~ImageProgressListener() {}
  1027. /**
  1028. * Called when the image manager has decoded some data, and is offering the user interface to
  1029. * handle user input, to avoid freezing the user interface. The ImageProgressListener should
  1030. * make sure that ImageManager::Progress() is called later on.
  1031. */
  1032. virtual void OnProgress() = 0;
  1033. #ifdef ASYNC_IMAGE_DECODERS_EMULATION
  1034. /**
  1035. * Only used when ASYNC_IMAGE_DECODERS_EMULATION is defined. Called when there is more data
  1036. * added to an image, that will need to be decoded later (asynchronously). The implementation
  1037. * calls the hidden img module function ImageManagerImp::MoreBufferedData(). It is possible
  1038. * that I move the function to ImageManager later, but since this is no code that should be
  1039. * used other than when emulating asynchronous image decoding, I will let it be like this for
  1040. * a while.
  1041. */
  1042. virtual void OnMoreBufferedData() = 0;
  1043. /**
  1044. * Only used when ASYNC_IMAGE_DECODERS_EMULATION is defined. Called when we have an ImageDecoder
  1045. * that will need to be deleted later. The ImageProgressListener should make sure that
  1046. * ImageManager::FreeUnusedAsyncDecoders() will be called later.
  1047. */
  1048. virtual void OnMoreDeletedDecoders() = 0;
  1049. #endif // ASYNC_IMAGE_DECODERS_EMULATION
  1050. };
  1051. /**
  1052. * It is possible to change the policy for what the image manager does with its images. The plan is
  1053. * to add more cache policies as soon as they are needed.
  1054. */
  1055. enum ImageCachePolicy
  1056. {
  1057. /**
  1058. * A soft image cache policy works like this. It is using a least recently used cache, trying to
  1059. * follow the cache limit in the ImageManager. However, a visible image cannot be thrown out of
  1060. * the cache, so it is possible that the cache limit will be exceeded from time to time.
  1061. */
  1062. IMAGE_CACHE_POLICY_SOFT,
  1063. /**
  1064. * The strict image cache policy is not implemented yet.
  1065. */
  1066. IMAGE_CACHE_POLICY_STRICT
  1067. };
  1068. class ImageDecoderFactory;
  1069. /**
  1070. * The ImageManager is the main interface between the rest of the code and the img module. One (and
  1071. * only one) ImageManager object should be created with ImageManager::Create, and it should be assigned
  1072. * to the global variable imgManager. The ImageManager is mainly responsible for caching image objects,
  1073. * keeping a list of all referenced images, and making sure that images are decoded properly. While decoding,
  1074. * the ImageManager will keep a list of loaded images that are not decoded completely yet. The ImageManager
  1075. * will make sure that decoding of images will not use too large time slice at once. This is to ensure that
  1076. * the user interface stays responsible during decoding.
  1077. */
  1078. class ImageManager
  1079. {
  1080. public:
  1081. /**
  1082. * Creates a ImageManager object. Should only be called once. The ImageManger should be saved in the global
  1083. * imgManager variable, since that variable is used internally in the img module.
  1084. * @param listener the ImageProgressListener that will be called when there are data to be decoded in at least one of the images belonging to the ImageManager.
  1085. * @return an ImageManager object, or NULL if OOM.
  1086. */
  1087. static ImageManager* Create(ImageProgressListener* listener);
  1088. /**
  1089. * Clears up the ImageManager and the rest of the img module.
  1090. * After this function is called, no functions or objects in the
  1091. * img module may be used.
  1092. */
  1093. virtual ~ImageManager() {}
  1094. /**
  1095. locks the image cache from purging. any call to FreeMemory will
  1096. be suppressed until UnlockImageCache is called.
  1097. */
  1098. virtual void LockImageCache() = 0;
  1099. /**
  1100. unlocks the image cache. calls FreeMemory if any call was made
  1101. while cache was locked.
  1102. this function will also set the current grace time, so that any
  1103. images in state of grace will not be purged too early (see
  1104. BeginGraceTime).
  1105. */
  1106. virtual void UnlockImageCache() = 0;
  1107. /**
  1108. Sometimes images are marked as no longer visible due to a
  1109. MarkExtraDirty-reflow removing its layout box. these images may
  1110. still be visible, in which case the next paint traversal will
  1111. mark them as such again. Because purging the image cache may
  1112. happen between the reflow and the traverse this can cause
  1113. images to be needlessly kicked out of the image cache only to
  1114. be subsequently redecoded. To remedy this a grace time can be
  1115. used, signaling that the image must not be purged until after a
  1116. specified amount of time has passed.
  1117. any images marked no longer visible between a call to
  1118. BeginGraceTime and EndGraceTime will be in state of grace, and
  1119. will not be purged until the time specified in
  1120. TWEAK_IMG_GRACE_TIME has passed.
  1121. should only be called when the image cache is locked from
  1122. purging (see LockImageCache).
  1123. */
  1124. virtual void BeginGraceTime() = 0;
  1125. /**
  1126. see BeginGraceTime
  1127. */
  1128. virtual void EndGraceTime() = 0;
  1129. /**
  1130. * Frees as much memory as possible used by the images in the system. With current cache
  1131. * policies, visible images cannot be freed.
  1132. */
  1133. virtual void FreeMemory() = 0;
  1134. /**
  1135. * Sets the cache size and the cache policy for the ImageManager.
  1136. * @param cache_size the size of the cache used by the img module in bytes.
  1137. * @param cache_policy the cache policy used in the img module, see ImageCachePolicy enumeration for documentation.
  1138. */
  1139. virtual void SetCacheSize(INT32 cache_size, ImageCachePolicy cache_policy) = 0;
  1140. /**
  1141. * Adds an ImageDecoderFactory to the ImageManager, to take care of decoding a specified image type.
  1142. * @return a OP_STATUS with OpStatus::ERR_NO_MEMORY or OpStatus::OK.
  1143. * @param factory the ImageDecoderFactory to add.
  1144. * @param type the type that this ImageDecoderFactory will handle. The image code doesn't know what the type value means, it only needs it to be unique for every decoder factory. The type may not be 0.
  1145. * @param check_header TRUE if we should check if a file with the wrong mime type, should be checked if it can be decoded by this ImageDecoderFactory.
  1146. */
  1147. virtual OP_STATUS AddImageDecoderFactory(ImageDecoderFactory* factory, INT32 type, BOOL check_header = TRUE) = 0;
  1148. #ifdef ASYNC_IMAGE_DECODERS
  1149. /**
  1150. * Sets the factory that will be used to create ImageDecoder objects for decoding images. When
  1151. * we are using asynchronous image decoders, the ImageDecoderFactory objects added with
  1152. * AddImageDecoderFactory will not be used to create ImageDecoder objects, only to check the
  1153. * type of an image, or the size of an image.
  1154. */
  1155. virtual void SetAsyncImageDecoderFactory(AsyncImageDecoderFactory* factory) = 0;
  1156. #endif // ASYNC_IMAGE_DECODERS
  1157. /**
  1158. * @return a Image correspodning to the ImageContentProvider. Will return an empty image if OOM (Image::IsEmpty() will return TRUE).
  1159. * @param content_provider the ImageContentProvider that represents the ImageRep that the Image will share.
  1160. */
  1161. virtual Image GetImage(ImageContentProvider* content_provider) = 0;
  1162. /**
  1163. * @return a Image which encapsulates a OpBitmap. Such bitmap cannot be redecoded or shared, but will stay in memory as long as there are references to the Image object.
  1164. * @param bitmap the bitmap to encapsulate.
  1165. */
  1166. virtual Image GetImage(OpBitmap* bitmap) = 0;
  1167. /**
  1168. * Resets an image, that is, all memory is freed, and all data such as Width() and Height() will
  1169. * disappear. The ImageContentProvider will still be there.
  1170. * @param content_provider the ImageContentProvider representing the ImageRep that we should reset.
  1171. */
  1172. virtual void ResetImage(ImageContentProvider* content_provider) = 0;
  1173. /**
  1174. * @return the type of the image with the given header. Will return 0 if image type for the header is unknown to the ImageManager.
  1175. * @param data_buf pointer to the data for the start of the image file.
  1176. * @param buf_len length of the data with the start of the image file.
  1177. */
  1178. virtual int CheckImageType(const unsigned char* data_buf, UINT32 buf_len) = 0;
  1179. /**
  1180. * @return TRUE if the type is a supported image type.
  1181. * @param type the type of image.
  1182. */
  1183. virtual BOOL IsImage(int type) = 0;
  1184. /**
  1185. * Decode a part of the next image in the decode queue. If we haven't finished decoding all of the
  1186. * images in the decode queue, ImageProgressListener::OnProgress will be called from this function.
  1187. */
  1188. virtual void Progress() = 0;
  1189. #ifdef ASYNC_IMAGE_DECODERS
  1190. /**
  1191. * Frees all unreferenced asynchronous ImageDecoder objects. Normally (when not using asynchronous
  1192. * image decoding) we delete the image decoder when loading fails. But, if we are decoding
  1193. * asynchronously, we are not able to destroy the image decoder immediately during decoding, since
  1194. * the image decoder object is referenced from outside the img module. Therefore, the img module
  1195. * just mark the image decoder for deletion, and deletes it when FreeUnusedAsyncDecoders() is called.
  1196. */
  1197. virtual void FreeUnusedAsyncDecoders() = 0;
  1198. #endif // ASYNC_IMAGE_DECODERS
  1199. #ifdef HAS_ATVEF_SUPPORT
  1200. /**
  1201. * @return a Image representing the atvef image. This image does not have any content, and will always return TRUE from Image::IsAtvefImage(). It is not possible to get an OOM condition when calling this function.
  1202. */
  1203. virtual Image GetAtvefImage() = 0;
  1204. #endif
  1205. virtual INT32 GetCacheSize() = 0;
  1206. virtual INT32 GetUsedCacheMem() = 0;
  1207. #ifdef IMG_CACHE_MULTIPLE_ANIMATION_FRAMES
  1208. virtual INT32 GetAnimCacheSize() = 0;
  1209. virtual INT32 GetUsedAnimCacheMem() = 0;
  1210. #endif // IMG_CACHE_MULTIPLE_ANIMATION_FRAMES
  1211. #ifdef CACHE_UNUSED_IMAGES
  1212. /**
  1213. * Frees all images for a given URL context.
  1214. */
  1215. virtual void FreeImagesForContext(URL_CONTEXT_ID id) = 0;
  1216. #endif // CACHE_UNUSED_IMAGES
  1217. /**
  1218. helper object for placing images in state of grace - locks
  1219. image cache and starts grace time mode. does the opposite on
  1220. destruction.
  1221. */
  1222. class GraceTimeLock
  1223. {
  1224. public:
  1225. GraceTimeLock(ImageManager* image_manager) : m_image_manager(image_manager)
  1226. {
  1227. OP_ASSERT(image_manager);
  1228. m_image_manager->LockImageCache();
  1229. m_image_manager->BeginGraceTime();
  1230. }
  1231. ~GraceTimeLock() { m_image_manager->EndGraceTime(); m_image_manager->UnlockImageCache(); }
  1232. private:
  1233. ImageManager* m_image_manager;
  1234. };
  1235. #ifdef IMG_TOGGLE_CACHE_UNUSED_IMAGES
  1236. virtual void CacheUnusedImages(BOOL strategy) = 0;
  1237. virtual BOOL IsCachingUnusedImages() const = 0;
  1238. #endif // IMG_TOGGLE_CACHE_UNUSED_IMAGES
  1239. };
  1240. #endif // !IMAGE_H