1 | /* |
2 | //C- ------------------------------------------------------------------- |
3 | //C- DjVuLibre-3.5 |
4 | //C- Copyright (c) 2002 Leon Bottou and Yann Le Cun. |
5 | //C- Copyright (c) 2001 AT&T |
6 | //C- |
7 | //C- This software is subject to, and may be distributed under, the |
8 | //C- GNU General Public License, either Version 2 of the license, |
9 | //C- or (at your option) any later version. The license should have |
10 | //C- accompanied the software or you may obtain a copy of the license |
11 | //C- from the Free Software Foundation at http://www.fsf.org . |
12 | //C- |
13 | //C- This program is distributed in the hope that it will be useful, |
14 | //C- but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | //C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
16 | //C- GNU General Public License for more details. |
17 | //C- |
18 | //C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from |
19 | //C- Lizardtech Software. Lizardtech Software has authorized us to |
20 | //C- replace the original DjVu(r) Reference Library notice by the following |
21 | //C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu): |
22 | //C- |
23 | //C- ------------------------------------------------------------------ |
24 | //C- | DjVu (r) Reference Library (v. 3.5) |
25 | //C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved. |
26 | //C- | The DjVu Reference Library is protected by U.S. Pat. No. |
27 | //C- | 6,058,214 and patents pending. |
28 | //C- | |
29 | //C- | This software is subject to, and may be distributed under, the |
30 | //C- | GNU General Public License, either Version 2 of the license, |
31 | //C- | or (at your option) any later version. The license should have |
32 | //C- | accompanied the software or you may obtain a copy of the license |
33 | //C- | from the Free Software Foundation at http://www.fsf.org . |
34 | //C- | |
35 | //C- | The computer code originally released by LizardTech under this |
36 | //C- | license and unmodified by other parties is deemed "the LIZARDTECH |
37 | //C- | ORIGINAL CODE." Subject to any third party intellectual property |
38 | //C- | claims, LizardTech grants recipient a worldwide, royalty-free, |
39 | //C- | non-exclusive license to make, use, sell, or otherwise dispose of |
40 | //C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the |
41 | //C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU |
42 | //C- | General Public License. This grant only confers the right to |
43 | //C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to |
44 | //C- | the extent such infringement is reasonably necessary to enable |
45 | //C- | recipient to make, have made, practice, sell, or otherwise dispose |
46 | //C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to |
47 | //C- | any greater extent that may be necessary to utilize further |
48 | //C- | modifications or combinations. |
49 | //C- | |
50 | //C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY |
51 | //C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED |
52 | //C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF |
53 | //C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |
54 | //C- +------------------------------------------------------------------ |
55 | */ |
56 | |
57 | #ifndef DDJVUAPI_H |
58 | #define DDJVUAPI_H |
59 | |
60 | #ifdef __cplusplus |
61 | extern "C" { |
62 | #endif |
63 | #if 0 |
64 | } |
65 | #endif |
66 | |
67 | #include <stddef.h> |
68 | #include <stdlib.h> |
69 | #include <stdio.h> |
70 | |
71 | #ifndef DDJVUAPI |
72 | # ifdef WIN32 |
73 | # ifdef DLL_EXPORT |
74 | # define DDJVUAPI __declspec(dllexport) |
75 | # else |
76 | # define DDJVUAPI __declspec(dllimport) |
77 | # endif |
78 | # endif |
79 | #endif |
80 | #ifndef DDJVUAPI |
81 | # define DDJVUAPI /**/ |
82 | #endif |
83 | |
84 | #ifndef TRUE |
85 | # define TRUE (1) |
86 | #endif |
87 | |
88 | #ifndef FALSE |
89 | # define FALSE (0) |
90 | #endif |
91 | |
92 | |
93 | |
94 | /* -------------------------------------------------- */ |
95 | /* DDJVU API */ |
96 | /* -------------------------------------------------- */ |
97 | |
98 | /* The DDJVU API provides for efficiently decoding and |
99 | displaying DjVu documents. It provides for displaying |
100 | images without waiting for the complete DjVu data. Images |
101 | can be displayed as soon as sufficient data is |
102 | available. A higher quality image might later be |
103 | displayed when further data is available. The DjVu |
104 | library achieves this using a complicated scheme |
105 | involving multiple threads. The DDJVU API hides this |
106 | complexity with a familiar event model. |
107 | */ |
108 | |
109 | /* Compiler symbol DDJVUAPI_VERSION tracks |
110 | backward compatible additions to the DDJVU API. |
111 | |
112 | Version Change |
113 | ----------------------------- |
114 | 21 Added: |
115 | reentrant version of miniexp input/output |
116 | 20 Added: |
117 | ddjvu_get_version_string() |
118 | ddjvu_format_set_white() |
119 | ddjvu_anno_get_xmp() |
120 | 19 Added: |
121 | ddjvu_document_create_by_filename_utf8() |
122 | 18 Added: |
123 | ddjvu_document_get_{anno,pagedump,filedump}() |
124 | Modifed (binary compatible): |
125 | ddjvu_document_get_{fileinfo,pageinfo}() |
126 | ddjvu_document_save() [--pages, --indirect=] |
127 | Deprecated: |
128 | ddjvu_document_search_pageno() |
129 | ddjvu_page_get_{short,long}_description() |
130 | 17 Added: |
131 | ddjvu_page_get_initial_rotation(), ddjvu_code_get_version() |
132 | ddjvu_document_{get_filenum,get_fileinfo}}() |
133 | ddjvu_document_{search_pageno,check_pagedata}() |
134 | ddjvu_rectmapper_t and related functions. |
135 | 16 Added: |
136 | miniexp.h and related functions. |
137 | 15 Added: |
138 | ddjvu_document_get_pageinfo() |
139 | ddjvu_document_print() |
140 | 14 Initial version. |
141 | */ |
142 | |
143 | #define DDJVUAPI_VERSION 21 |
144 | |
145 | typedef struct ddjvu_context_s ddjvu_context_t; |
146 | typedef union ddjvu_message_s ddjvu_message_t; |
147 | typedef struct ddjvu_job_s ddjvu_job_t; |
148 | typedef struct ddjvu_document_s ddjvu_document_t; |
149 | typedef struct ddjvu_page_s ddjvu_page_t; |
150 | typedef struct ddjvu_format_s ddjvu_format_t; |
151 | typedef struct ddjvu_rect_s ddjvu_rect_t; |
152 | typedef struct ddjvu_rectmapper_s ddjvu_rectmapper_t; |
153 | |
154 | |
155 | /* GENERAL CONVENTIONS: |
156 | |
157 | - all strings use locale encoding (unless specified otherwise). |
158 | - all filenames are unencoded byte strings, |
159 | - all errors are signaled with error event messages, |
160 | - all functions returning a pointer might return a null pointer. |
161 | |
162 | HEADER: |
163 | Always use the following idiom to include this file. |
164 | |
165 | #include <libdjvu/ddjvuapi.h> |
166 | #include <libdjvu/miniexp.h> |
167 | |
168 | This file does not declare functions ddjvu_get_DjVuImage() |
169 | and djvu_get_DjVuDocument() unless you include files |
170 | "DjVuImage.h" and "DjVuDocument.h" before this file. |
171 | |
172 | PREREQUISITES: |
173 | - Please read the djvu man page: <"tools/djvu.1">. |
174 | - Please browse the file format specifications |
175 | <"doc/djvu3changes.txt"> and <"doc/djvu3spec.djvu">. |
176 | */ |
177 | |
178 | |
179 | |
180 | /* -------------------------------------------------- */ |
181 | /* DDJVU_CONTEXT_T */ |
182 | /* -------------------------------------------------- */ |
183 | |
184 | /* There is usually only one <ddjvu_context_t> object. |
185 | This object holds global data structures such as the |
186 | cache of decoded pages, or the list of pending |
187 | event messages. |
188 | */ |
189 | |
190 | |
191 | |
192 | /* ddjvu_get_version_string() --- |
193 | Returns a string that described the underlying code. */ |
194 | |
195 | DDJVUAPI const char* |
196 | ddjvu_get_version_string(void); |
197 | |
198 | |
199 | /* ddjvu_context_create --- |
200 | Creates a <ddjvu_context_t> object. |
201 | Argument <programname> is the name of the calling executable. */ |
202 | |
203 | DDJVUAPI ddjvu_context_t * |
204 | ddjvu_context_create(const char *programname); |
205 | |
206 | |
207 | /* ddjvu_context_release --- |
208 | Release a reference to a <ddjvu_context_t> object. |
209 | The calling program should no longer reference this object. |
210 | The object itself will be destroyed as soon as no other object |
211 | or thread needs it. */ |
212 | |
213 | DDJVUAPI void |
214 | ddjvu_context_release(ddjvu_context_t *context); |
215 | |
216 | |
217 | |
218 | |
219 | |
220 | /* ------- CACHE ------- */ |
221 | |
222 | /* ddjvu_cache_set_size --- |
223 | Sets the maximum size of the cache of decoded page data. |
224 | The argument is expressed in bytes. */ |
225 | |
226 | DDJVUAPI void |
227 | ddjvu_cache_set_size(ddjvu_context_t *context, |
228 | unsigned long cachesize); |
229 | |
230 | |
231 | /* ddjvu_cache_get_size --- |
232 | Returns the maximum size of the cache. */ |
233 | |
234 | DDJVUAPI unsigned long |
235 | ddjvu_cache_get_size(ddjvu_context_t *context); |
236 | |
237 | |
238 | /* ddjvu_cache_clear --- |
239 | Clears all cached data. */ |
240 | |
241 | DDJVUAPI void |
242 | ddjvu_cache_clear(ddjvu_context_t *context); |
243 | |
244 | |
245 | |
246 | /* ------- MESSAGE QUEUE ------- */ |
247 | |
248 | /* Messages produced by the ddjvu api accumulate into |
249 | the message queue. Processing messages is not optional! |
250 | A typical message handling routine looks like this: |
251 | |
252 | void handle_ddjvu_messages(ddjvu_context_t *ctx, int wait) |
253 | { |
254 | const ddjvu_message_t *msg; |
255 | if (wait) |
256 | ddjvu_message_wait(ctx); |
257 | while ((msg = ddjvu_message_peek(ctx))) |
258 | { |
259 | switch(msg->m_any.tag) |
260 | { |
261 | case DDJVU_ERROR: .... ; break; |
262 | case DDJVU_INFO: .... ; break; |
263 | case DDJVU_NEWSTREAM: .... ; break; |
264 | .... |
265 | default: break; |
266 | } |
267 | ddjvu_message_pop(ctx); |
268 | } |
269 | } |
270 | */ |
271 | |
272 | |
273 | /* ddjvu_message_peek --- |
274 | Returns a pointer to the next DDJVU message. |
275 | This function returns 0 if no message is available. |
276 | It does not remove the message from the queue. */ |
277 | |
278 | DDJVUAPI ddjvu_message_t * |
279 | ddjvu_message_peek(ddjvu_context_t *context); |
280 | |
281 | |
282 | /* ddjvu_message_wait --- |
283 | Returns a pointer to the next DDJVU message. |
284 | This function waits until a message is available. |
285 | It does not remove the message from the queue. */ |
286 | |
287 | DDJVUAPI ddjvu_message_t * |
288 | ddjvu_message_wait(ddjvu_context_t *context); |
289 | |
290 | |
291 | /* ddjvu_message_pop --- |
292 | Removes one message from the queue. |
293 | This function must be called after processing the message. |
294 | Pointers returned by previous calls to <ddjvu_message_peek> |
295 | or <ddjvu_message_wait> are no longer valid after |
296 | calling <ddjvu_message_pop>. */ |
297 | |
298 | DDJVUAPI void |
299 | ddjvu_message_pop(ddjvu_context_t *context); |
300 | |
301 | |
302 | /* ddjvu_message_set_callback --- |
303 | Defines a callback function invoked whenever |
304 | a new message is posted to the ddjvuapi message queue, |
305 | and returns a pointer to the previous callback function. |
306 | This callback function can be called at any time |
307 | while other code is executing. Do not call ddjvuapi |
308 | functions from this callback. It should simply signal |
309 | the main application event loop that new ddjvuapi messages |
310 | are available. Under WIN32, this is usually achieved |
311 | by posting a user window message. Under UNIX, this is |
312 | usually achieved using a pipe: the callback writes |
313 | a single byte into the pipe; the main application loop |
314 | monitors the reading end of the pipe and detects |
315 | the presence of data. */ |
316 | |
317 | typedef void |
318 | (*ddjvu_message_callback_t)(ddjvu_context_t *context, void *closure); |
319 | |
320 | DDJVUAPI void |
321 | ddjvu_message_set_callback(ddjvu_context_t *context, |
322 | ddjvu_message_callback_t callback, |
323 | void *closure); |
324 | |
325 | |
326 | |
327 | /* -------------------------------------------------- */ |
328 | /* DDJVU_JOB_T */ |
329 | /* -------------------------------------------------- */ |
330 | |
331 | |
332 | /* Many essential ddjvuapi functions initiate asynchronous operations. |
333 | These "jobs" run in seperate threads and report their |
334 | progress by posting messages into the ddjvu context event queue. |
335 | Jobs are sometimes represented by a ddjvu_job_t object. */ |
336 | |
337 | /* ddjvu_job_status --- |
338 | Returns the status of the specified job. */ |
339 | |
340 | typedef enum { |
341 | DDJVU_JOB_NOTSTARTED, /* operation was not even started */ |
342 | DDJVU_JOB_STARTED, /* operation is in progress */ |
343 | DDJVU_JOB_OK, /* operation terminated successfully */ |
344 | DDJVU_JOB_FAILED, /* operation failed because of an error */ |
345 | DDJVU_JOB_STOPPED /* operation was interrupted by user */ |
346 | } ddjvu_status_t; |
347 | |
348 | DDJVUAPI ddjvu_status_t |
349 | ddjvu_job_status(ddjvu_job_t *job); |
350 | |
351 | #define ddjvu_job_done(job) \ |
352 | (ddjvu_job_status(job) >= DDJVU_JOB_OK) |
353 | #define ddjvu_job_error(job) \ |
354 | (ddjvu_job_status(job) >= DDJVU_JOB_FAILED) |
355 | |
356 | |
357 | /* ddjvu_job_stop --- |
358 | Attempts to cancel the specified job. |
359 | This is a best effort function. |
360 | There no guarantee that the job will |
361 | actually stop. |
362 | */ |
363 | |
364 | DDJVUAPI void |
365 | ddjvu_job_stop(ddjvu_job_t *job); |
366 | |
367 | |
368 | /* ddjvu_job_set_user_data --- |
369 | ddjvu_job_get_user_data --- |
370 | Each job can store an arbitrary pointer |
371 | that callers can use for any purpose. These two |
372 | functions provide for accessing or setting this pointer. |
373 | This pointer is cleared when the job is released */ |
374 | |
375 | DDJVUAPI void |
376 | ddjvu_job_set_user_data(ddjvu_job_t *job, void *userdata); |
377 | |
378 | DDJVUAPI void * |
379 | ddjvu_job_get_user_data(ddjvu_job_t *job); |
380 | |
381 | |
382 | /* ddjvu_job_release --- |
383 | Releases a reference to a job object and clears its user |
384 | data field. This does not cause the job to stop executing. |
385 | The calling program should no longer reference this object. |
386 | The object itself will be destroyed as soon as no |
387 | other object or thread needs it. |
388 | */ |
389 | |
390 | DDJVUAPI void |
391 | ddjvu_job_release(ddjvu_job_t *job); |
392 | |
393 | |
394 | |
395 | /* -------------------------------------------------- */ |
396 | /* DDJVU_MESSAGE_T */ |
397 | /* -------------------------------------------------- */ |
398 | |
399 | |
400 | /* ddjvu_message_t --- |
401 | This union type represents messages delivered by the |
402 | DDJVU API. Each member of the union pertains to a |
403 | specific kind of message. Member <m_any> represents the |
404 | information common to all kinds of messages. Given a |
405 | pointer <p> to a <djvu_message_t>, the message kind can |
406 | be accessed as <"p->m_any.tag">. */ |
407 | |
408 | |
409 | /* ddjvu_message_tag_t --- |
410 | This enumerated type identifies each kind of |
411 | message delivered by the DDJVU API. */ |
412 | |
413 | typedef enum { |
414 | DDJVU_ERROR, |
415 | DDJVU_INFO, |
416 | DDJVU_NEWSTREAM, |
417 | DDJVU_DOCINFO, |
418 | DDJVU_PAGEINFO, |
419 | DDJVU_RELAYOUT, |
420 | DDJVU_REDISPLAY, |
421 | DDJVU_CHUNK, |
422 | DDJVU_THUMBNAIL, |
423 | DDJVU_PROGRESS, |
424 | } ddjvu_message_tag_t; |
425 | |
426 | |
427 | /* ddjvu_message_t::m_any --- |
428 | This structure is a member of the union <djvu_message_t>. |
429 | It represents the information common to all kinds of |
430 | messages. Member <tag> indicates the kind of message. |
431 | Members <context>, <document>, <page>, and <job> indicate |
432 | the origin of the message. These fields contain null |
433 | pointers when they are not relevant. |
434 | These fields are also cleared when the corresponding |
435 | object is released with <ddjvu_{job,page,document}_release>. |
436 | If the message has not yet been passed to the user |
437 | with <ddjvu_message_{peek,wait}>, it is silently |
438 | removed from the message queue. */ |
439 | |
440 | typedef struct ddjvu_message_any_s { |
441 | ddjvu_message_tag_t tag; |
442 | ddjvu_context_t *context; |
443 | ddjvu_document_t *document; |
444 | ddjvu_page_t *page; |
445 | ddjvu_job_t *job; |
446 | } ddjvu_message_any_t; |
447 | |
448 | |
449 | /* ddjvu_message_t::m_error --- |
450 | Error messages are generated whenever the decoder or the |
451 | DDJVU API encounters an error condition. All errors are |
452 | reported as error messages because they can occur |
453 | asynchronously. Member <message> is the error message. |
454 | Members <function>, <filename> and <lineno> |
455 | indicates the place where the error was detected. */ |
456 | |
457 | struct ddjvu_message_error_s { /* ddjvu_message_t::m_error */ |
458 | ddjvu_message_any_t any; |
459 | const char *message; |
460 | const char *function; |
461 | const char *filename; |
462 | int lineno; |
463 | }; |
464 | |
465 | |
466 | /* ddjvu_message_t::m_info --- |
467 | This messages provides informational text indicating |
468 | the progress of the decoding process. This might |
469 | be displayed in the browser status bar. */ |
470 | |
471 | struct ddjvu_message_info_s { /* ddjvu_message_t::m_info */ |
472 | ddjvu_message_any_t any; |
473 | const char *message; |
474 | }; |
475 | |
476 | |
477 | |
478 | |
479 | /* -------------------------------------------------- */ |
480 | /* DDJVU_DOCUMENT_T */ |
481 | /* -------------------------------------------------- */ |
482 | |
483 | |
484 | /* ddjvu_document_create --- |
485 | Creates a decoder for a DjVu document and starts |
486 | decoding. This function returns immediately. The |
487 | decoding job then generates messages to request the raw |
488 | data and to indicate the state of the decoding process. |
489 | |
490 | Argument <url> specifies an optional URL for the document. |
491 | The URL follows the usual syntax (<"protocol://machine/path">). |
492 | It should not end with a slash. It only serves two purposes: |
493 | - The URL is used as a key for the cache of decoded pages. |
494 | - The URL is used to document <m_newstream> messages. |
495 | |
496 | Setting argument <cache> to <TRUE> indicates that decoded pages |
497 | should be cached when possible. This only works when |
498 | argument <url> is not the null pointer. |
499 | |
500 | It is important to understand that the URL is not used to |
501 | access the data. The document generates <m_newstream> |
502 | messages to indicate which data is needed. The caller must |
503 | then provide the raw data using <ddjvu_stream_write> |
504 | and <ddjvu_stream_close>. |
505 | |
506 | Localized characters in argument <url> should be in |
507 | urlencoded UTF-8 (like "%2A"). What is happening for non |
508 | ascii characters is unclear (probably UTF-8). */ |
509 | |
510 | DDJVUAPI ddjvu_document_t * |
511 | ddjvu_document_create(ddjvu_context_t *context, |
512 | const char *url, |
513 | int cache); |
514 | |
515 | |
516 | /* ddjvu_document_create_by_filename --- |
517 | Creates a document for a DjVu document stored in a file. |
518 | The document will directly access the specified DjVu file |
519 | or related files without generating <m_newstream> messages. |
520 | The standard function expects the filename in locale encoding. |
521 | The utf8 variant expects an utf8 encoded filename. */ |
522 | |
523 | DDJVUAPI ddjvu_document_t * |
524 | ddjvu_document_create_by_filename(ddjvu_context_t *context, |
525 | const char *filename, |
526 | int cache); |
527 | |
528 | DDJVUAPI ddjvu_document_t * |
529 | ddjvu_document_create_by_filename_utf8(ddjvu_context_t *context, |
530 | const char *filename, |
531 | int cache); |
532 | |
533 | /* ddjvu_document_job --- |
534 | Access the job object in charge of decoding the document header. |
535 | In fact <ddjvu_document_t> is a subclass of <ddjvu_job_t> |
536 | and this function is a type cast. */ |
537 | |
538 | DDJVUAPI ddjvu_job_t * |
539 | ddjvu_document_job(ddjvu_document_t *document); |
540 | |
541 | |
542 | /* ddjvu_document_release --- |
543 | Release a reference to a <ddjvu_document_t> object. |
544 | The calling program should no longer reference this object. |
545 | The object itself will be destroyed as soon as no other object |
546 | or thread needs it. */ |
547 | |
548 | #define ddjvu_document_release(document) \ |
549 | ddjvu_job_release(ddjvu_document_job(document)) |
550 | |
551 | |
552 | /* ddjvu_document_set_user_data --- |
553 | ddjvu_document_get_user_data --- |
554 | Each <ddjvu_document_t> object can store an arbitray pointer |
555 | that callers can use for any purpose. These two functions |
556 | provide for accessing or setting this pointer. */ |
557 | |
558 | #define ddjvu_document_set_user_data(document,userdata) \ |
559 | ddjvu_job_set_user_data(ddjvu_document_job(document),userdata) |
560 | #define ddjvu_document_get_user_data(document) \ |
561 | ddjvu_job_get_user_data(ddjvu_document_job(document)) |
562 | |
563 | /* ddjvu_document_decoding_status --- |
564 | ddjvu_document_decoding_done, ddjvu_document_decoding_error --- |
565 | This function returns the status of the document header decoding job */ |
566 | |
567 | #define ddjvu_document_decoding_status(document) \ |
568 | ddjvu_job_status(ddjvu_document_job(document)) |
569 | #define ddjvu_document_decoding_done(document) \ |
570 | (ddjvu_document_decoding_status(document) >= DDJVU_JOB_OK) |
571 | #define ddjvu_document_decoding_error(document) \ |
572 | (ddjvu_document_decoding_status(document) >= DDJVU_JOB_FAILED) |
573 | |
574 | |
575 | /* ------- STREAMS ------- */ |
576 | |
577 | |
578 | /* ddjvu_message_t::m_newstream --- |
579 | Newstream messages are generated whenever the decoder |
580 | needs to access raw DjVu data. The caller must then |
581 | provide the requested data using <ddjvu_stream_write> |
582 | and <ddjvu_stream_close>. |
583 | |
584 | In the case of indirect documents, a single decoder |
585 | might simultaneously request several streams of data. |
586 | Each stream is identified by a small integer <streamid>. |
587 | |
588 | The first <m_newstream> message always has member |
589 | <streamid> set to zero and member <name> set to the null |
590 | pointer. It indicates that the decoder needs to access |
591 | the data in the main DjVu file. In fact, data can be |
592 | written to stream <0> as soon as the <ddjvu_document_t> |
593 | object is created. |
594 | |
595 | Further <m_newstream> messages are generated to access |
596 | the auxiliary files of indirect or indexed DjVu |
597 | documents. Member <name> then provides the basename of |
598 | the auxiliary file. |
599 | |
600 | Member <url> is set according to the url argument |
601 | provided to function <ddjvu_document_create>. The first |
602 | newstream message always contain the url passed to |
603 | <ddjvu_document_create>. Subsequent newstream messages |
604 | contain the url of the auxiliary files for indirect or |
605 | indexed DjVu documents. */ |
606 | |
607 | struct ddjvu_message_newstream_s { /* ddjvu_message_t::m_newstream */ |
608 | ddjvu_message_any_t any; |
609 | int streamid; |
610 | const char *name; |
611 | const char *url; |
612 | }; |
613 | |
614 | |
615 | /* ddjvu_stream_write --- |
616 | Provide raw data to the DjVu decoder. |
617 | This function should be called as soon as the data is available, |
618 | for instance when receiving DjVu data from a network connection. |
619 | */ |
620 | |
621 | DDJVUAPI void |
622 | ddjvu_stream_write(ddjvu_document_t *document, |
623 | int streamid, |
624 | const char *data, |
625 | unsigned long datalen ); |
626 | |
627 | |
628 | /* ddjvu_stream_close --- |
629 | Indicates that no more data will be provided on a |
630 | particular stream. Argument <stop> most likely should be |
631 | set to <FALSE>. Setting argument <stop> to <TRUE> |
632 | indicates that the user has interrupted the data transfer |
633 | (for instance by pressing the stop button of a browser) |
634 | and that the decoding threads should be stopped as |
635 | soon as feasible. */ |
636 | |
637 | DDJVUAPI void |
638 | ddjvu_stream_close(ddjvu_document_t *document, |
639 | int streamid, |
640 | int stop ); |
641 | |
642 | |
643 | |
644 | /* ------- QUERIES ------- */ |
645 | |
646 | |
647 | /* ddjvu_message_t::m_docinfo --- |
648 | The <m_docinfo> message indicates that basic information |
649 | about the document has been obtained and decoded. |
650 | Not much can be done before this happens. |
651 | Call <ddjvu_document_decoding_status> to determine |
652 | whether the operation was successful. */ |
653 | |
654 | struct ddjvu_message_docinfo_s { |
655 | ddjvu_message_any_t any; |
656 | }; |
657 | |
658 | |
659 | /* ddjvu_document_get_type --- |
660 | Returns the type of a DjVu document. |
661 | This function might return <DDJVU_DOCTYPE_UNKNOWN> |
662 | when called before receiving a <m_docinfo> message. */ |
663 | |
664 | typedef enum { |
665 | DDJVU_DOCTYPE_UNKNOWN=0, |
666 | DDJVU_DOCTYPE_SINGLEPAGE, |
667 | DDJVU_DOCTYPE_BUNDLED, |
668 | DDJVU_DOCTYPE_INDIRECT, |
669 | DDJVU_DOCTYPE_OLD_BUNDLED, /* obsolete */ |
670 | DDJVU_DOCTYPE_OLD_INDEXED, /* obsolete */ |
671 | } ddjvu_document_type_t; |
672 | |
673 | DDJVUAPI ddjvu_document_type_t |
674 | ddjvu_document_get_type(ddjvu_document_t *document); |
675 | |
676 | |
677 | /* ddjvu_document_get_pagenum --- |
678 | Returns the number of pages in a DjVu document. |
679 | This function might return 1 when called |
680 | before receiving a <m_docinfo> message */ |
681 | |
682 | DDJVUAPI int |
683 | ddjvu_document_get_pagenum(ddjvu_document_t *document); |
684 | |
685 | |
686 | |
687 | /* ------- ADVANCED ------- */ |
688 | |
689 | |
690 | /* ddjvu_document_get_filenum -- |
691 | Returns the number of component files. |
692 | This function might return 0 when called |
693 | before receiving a <m_docinfo> message */ |
694 | |
695 | DDJVUAPI int |
696 | ddjvu_document_get_filenum(ddjvu_document_t *document); |
697 | |
698 | |
699 | /* ddjvu_document_get_fileinfo -- |
700 | Returns information about component file <fileno>. |
701 | This function might return <DDJVU_JOB_STARTED> when |
702 | called before receiving a <m_docinfo> message. |
703 | String pointers in the returned data structure |
704 | might be null. Strings are UTF8 encoded and remain |
705 | allocated as long as the ddjvu_document_t object exists. |
706 | |
707 | Changes for ddjvuapi=18 |
708 | - Redefined as a macro passing the structure size. |
709 | */ |
710 | |
711 | typedef struct ddjvu_fileinfo_s { |
712 | char type; /* [P]age, [T]humbnails, [I]nclude. */ |
713 | int pageno; /* Negative when not applicable. */ |
714 | int size; /* Negative when unknown. */ |
715 | const char *id; /* File identifier. */ |
716 | const char *name; /* Name for indirect documents. */ |
717 | const char *title; /* Page title. */ |
718 | } ddjvu_fileinfo_t; |
719 | |
720 | #define ddjvu_document_get_fileinfo(d,f,i) \ |
721 | ddjvu_document_get_fileinfo_imp(d,f,i,sizeof(ddjvu_fileinfo_t)) |
722 | |
723 | DDJVUAPI ddjvu_status_t |
724 | ddjvu_document_get_fileinfo_imp(ddjvu_document_t *document, int fileno, |
725 | ddjvu_fileinfo_t *info, unsigned int infosz); |
726 | |
727 | |
728 | /* ddjvu_document_search_pageno --- DEPRECATED. */ |
729 | |
730 | DDJVUAPI int ddjvu_document_search_pageno(ddjvu_document_t*, const char*); |
731 | |
732 | |
733 | /* ddjvu_document_check_pagedata --- |
734 | Returns a non zero result if the data for page <pageno> |
735 | is already in memory. When this is the case, functions |
736 | <ddjvu_document_get_pageinfo> and <ddjvu_document_get_pagetext> |
737 | return the information immediately. |
738 | This function causes the emission of <m_pageinfo> messages |
739 | with zero in the <m_any.page> field whenever a new file |
740 | is completely downloaded. */ |
741 | |
742 | DDJVUAPI int |
743 | ddjvu_document_check_pagedata(ddjvu_document_t *document, int pageno); |
744 | |
745 | |
746 | /* ddjvu_document_get_pageinfo --- |
747 | Attempts to obtain information about page <pageno> |
748 | without decoding the page. If the information is available, |
749 | the function returns <DDJVU_JOB_OK> and fills the <info> structure. |
750 | Otherwise it starts fetching page data and returns <DDJVU_JOB_STARTED>. |
751 | This function causes the emission of <m_pageinfo> messages |
752 | with zero in the <m_any.page> field. |
753 | Typical synchronous usage: |
754 | |
755 | ddjvu_status_t r; |
756 | ddjvu_pageinfo_t info; |
757 | while ((r=ddjvu_document_get_pageinfo(doc,pageno,&info))<DDJVU_JOB_OK) |
758 | handle_ddjvu_messages(ctx, TRUE); |
759 | if (r>=DDJVU_JOB_FAILED) |
760 | signal_error(); |
761 | |
762 | Changes for ddjvuapi=18 |
763 | - Redefined as a macro passing the structure size. |
764 | - Added fields 'rotation' and 'version'. |
765 | */ |
766 | |
767 | typedef struct ddjvu_pageinfo_s { |
768 | int width; /* page width (in pixels) */ |
769 | int height; /* page height (in pixels) */ |
770 | int dpi; /* page resolution (in dots per inche) */ |
771 | int rotation; /* initial page orientation */ |
772 | int version; /* page version */ |
773 | } ddjvu_pageinfo_t; |
774 | |
775 | #define ddjvu_document_get_pageinfo(d,p,i) \ |
776 | ddjvu_document_get_pageinfo_imp(d,p,i,sizeof(ddjvu_pageinfo_t)) |
777 | |
778 | DDJVUAPI ddjvu_status_t |
779 | ddjvu_document_get_pageinfo_imp(ddjvu_document_t *document, int pageno, |
780 | ddjvu_pageinfo_t *info, unsigned int infosz ); |
781 | |
782 | |
783 | |
784 | |
785 | /* ddjvu_document_get_pagedump -- |
786 | This function returns a UTF8 encoded text describing the contents |
787 | of page <pageno> using the same format as command <djvudump>. |
788 | The returned string must be deallocated using <free()>. |
789 | It returns <0> when the information is not yet available. |
790 | It may then cause then the emission of <m_pageinfo> |
791 | messages with null <m_any.page>. |
792 | */ |
793 | |
794 | DDJVUAPI char * |
795 | ddjvu_document_get_pagedump(ddjvu_document_t *document, int pageno); |
796 | |
797 | |
798 | /* ddjvu_document_get_filedump -- |
799 | This function returns a UTF8 encoded text describing the contents |
800 | of file <fileno> using the same format as command <djvudump>. |
801 | The returned string must be deallocated using <free()>. |
802 | It returns <0> when the information is not yet available. |
803 | It may then cause then the emission of <m_pageinfo> |
804 | messages with null <m_any.page>. |
805 | */ |
806 | |
807 | DDJVUAPI char * |
808 | ddjvu_document_get_filedump(ddjvu_document_t *document, int fileno); |
809 | |
810 | |
811 | |
812 | |
813 | /* -------------------------------------------------- */ |
814 | /* DJVU_PAGE_T */ |
815 | /* -------------------------------------------------- */ |
816 | |
817 | |
818 | /* ddjvu_page_create_by_pageno --- |
819 | Each page of a document can be accessed by creating a |
820 | <ddjvu_page_t> object with this function. Argument |
821 | <pageno> indicates the page number, starting with page |
822 | <0> to <pagenum-1>. This function may return NULL |
823 | when called before receiving the <m_docinfo> message. |
824 | Calling this function also initiates the data transfer |
825 | and the decoding threads for the specified page. |
826 | Various messages will document the progress of these |
827 | operations. Error messages will be generated if |
828 | the page does not exists. */ |
829 | |
830 | DDJVUAPI ddjvu_page_t * |
831 | ddjvu_page_create_by_pageno(ddjvu_document_t *document, |
832 | int pageno); |
833 | |
834 | /* ddjvu_page_create_by_pageid --- |
835 | This function is similar to <ddjvu_page_create_by_pageno> |
836 | but identifies the desired page by name instead of page |
837 | number. */ |
838 | |
839 | DDJVUAPI ddjvu_page_t * |
840 | ddjvu_page_create_by_pageid(ddjvu_document_t *document, |
841 | const char *pageid); |
842 | |
843 | |
844 | /* ddjvu_page_job --- |
845 | Access the job object in charge of decoding the document header. |
846 | In fact <ddjvu_page_t> is a subclass of <ddjvu_job_t> |
847 | and this function is a type cast. */ |
848 | |
849 | DDJVUAPI ddjvu_job_t * |
850 | ddjvu_page_job(ddjvu_page_t *page); |
851 | |
852 | |
853 | /* ddjvu_page_release --- |
854 | Release a reference to a <ddjvu_page_t> object. |
855 | The calling program should no longer reference this object. |
856 | The object itself will be destroyed as soon as no other object |
857 | or thread needs it. */ |
858 | |
859 | #define ddjvu_page_release(page) \ |
860 | ddjvu_job_release(ddjvu_page_job(page)) |
861 | |
862 | |
863 | /* ddjvu_page_set_user_data --- |
864 | ddjvu_page_get_user_data --- |
865 | Each <ddjvu_paqge_t> object can store an arbitray pointer |
866 | that callers can use for any purpose. These two functions |
867 | provide for accessing or setting this pointer. */ |
868 | |
869 | #define ddjvu_page_set_user_data(page,userdata) \ |
870 | ddjvu_job_set_user_data(ddjvu_page_job(page),userdata) |
871 | #define ddjvu_page_get_user_data(page) \ |
872 | ddjvu_job_get_user_data(ddjvu_page_job(page)) |
873 | |
874 | /* ddjvu_page_decoding_status --- |
875 | ddjvu_page_decoding_done --- |
876 | ddjvu_page_decoding_error --- |
877 | These calls return the status of the page decoding job. */ |
878 | |
879 | #define ddjvu_page_decoding_status(page) \ |
880 | ddjvu_job_status(ddjvu_page_job(page)) |
881 | #define ddjvu_page_decoding_done(page) \ |
882 | (ddjvu_page_decoding_status(page) >= DDJVU_JOB_OK) |
883 | #define ddjvu_page_decoding_error(page) \ |
884 | (ddjvu_page_decoding_status(page) >= DDJVU_JOB_FAILED) |
885 | |
886 | |
887 | /* ------- MESSAGES ------- */ |
888 | |
889 | |
890 | /* ddjvu_message_t::m_pageinfo --- |
891 | The page decoding process generates this message |
892 | - when basic page information is available and |
893 | before any <m_relayout> or <m_redisplay> message, |
894 | - when the page decoding thread terminates. |
895 | You can distinguish both cases using |
896 | function ddjvu_page_decoding_status(). |
897 | Messages <m_pageinfo> are also generated as a consequence of |
898 | functions such as <ddjvu_document_get_pageinfo>. |
899 | The field <m_any.page> of such message is null. |
900 | */ |
901 | |
902 | struct ddjvu_message_pageinfo_s { /* ddjvu_message_t::m_pageinfo */ |
903 | ddjvu_message_any_t any; |
904 | }; |
905 | |
906 | |
907 | /* ddjvu_message_t::m_relayout --- |
908 | This message is generated when a DjVu viewer |
909 | should recompute the layout of the page viewer |
910 | because the page size and resolution information has |
911 | been updated. */ |
912 | |
913 | struct ddjvu_message_relayout_s { /* ddjvu_message_t::m_relayout */ |
914 | ddjvu_message_any_t any; |
915 | }; |
916 | |
917 | |
918 | /* ddjvu_message_t::m_redisplay --- |
919 | This message is generated when a DjVu viewer |
920 | should call <ddjvu_page_render> and redisplay |
921 | the page. This happens, for instance, when newly |
922 | decoded DjVu data provides a better image. */ |
923 | |
924 | struct ddjvu_message_redisplay_s { /* ddjvu_message_t::m_redisplay */ |
925 | ddjvu_message_any_t any; |
926 | }; |
927 | |
928 | |
929 | /* ddjvu_message_t::m_chunk --- |
930 | This message indicates that an additional chunk |
931 | of DjVu data has been decoded. Member <chunkid> |
932 | indicates the type of the DjVu chunk. */ |
933 | |
934 | struct ddjvu_message_chunk_s { /* ddjvu_message_t::m_chunk */ |
935 | ddjvu_message_any_t any; |
936 | const char *chunkid; |
937 | }; |
938 | |
939 | /* About page messages -- |
940 | Both the <m_relayout> and <m_redisplay> messages are derived from the |
941 | <m_chunk> message. They are intended for driving a djvu image viewer. |
942 | When receiving <m_relayout>, the viewer should get the image size, decide |
943 | zoom factors, and place the image area, scrollbars, toolbars, and other gui |
944 | objects. When receiving <m_redisplay>, the viewer should invalidate the |
945 | image area so that the gui toolkit calls the repaint event handler. This |
946 | handler should call ddjvu_page_render() and paint the part of the |
947 | image that needs repainting. */ |
948 | |
949 | |
950 | |
951 | /* ------- QUERIES ------- */ |
952 | |
953 | /* ddjvu_page_get_width --- |
954 | Returns the page width in pixels. Calling this function |
955 | before receiving a <m_pageinfo> message always yields <0>. */ |
956 | |
957 | DDJVUAPI int |
958 | ddjvu_page_get_width(ddjvu_page_t *page); |
959 | |
960 | |
961 | /* ddjvu_page_get_height--- |
962 | Returns the page height in pixels. Calling this function |
963 | before receiving a <m_pageinfo> message always yields <0>. */ |
964 | |
965 | DDJVUAPI int |
966 | ddjvu_page_get_height(ddjvu_page_t *page); |
967 | |
968 | /* ddjvu_page_get_resolution --- |
969 | Returns the page resolution in pixels per inch (dpi). |
970 | Calling this function before receiving a <m_pageinfo> |
971 | message yields a meaningless but plausible value. */ |
972 | |
973 | DDJVUAPI int |
974 | ddjvu_page_get_resolution(ddjvu_page_t *page); |
975 | |
976 | |
977 | /* ddjvu_page_get_gamma --- |
978 | Returns the gamma of the display for which this page was designed. |
979 | Calling this function before receiving a <m_pageinfo> |
980 | message yields a meaningless but plausible value. */ |
981 | |
982 | DDJVUAPI double |
983 | ddjvu_page_get_gamma(ddjvu_page_t *page); |
984 | |
985 | |
986 | /* ddjvu_page_get_version --- |
987 | Returns the version of the djvu file format. |
988 | Calling this function before receiving a <m_pageinfo> |
989 | message yields a meaningless but plausible value. */ |
990 | |
991 | DDJVUAPI int |
992 | ddjvu_page_get_version(ddjvu_page_t *page); |
993 | |
994 | /* ddjvu_code_get_version --- |
995 | Returns the version of the djvu file format |
996 | implemented by this library. More or less graceful |
997 | degradation might arise if this is smaller than |
998 | the number returned by <ddjvu_page_get_version>. */ |
999 | |
1000 | DDJVUAPI int |
1001 | ddjvu_code_get_version(void); |
1002 | |
1003 | |
1004 | /* ddjvu_page_get_type --- |
1005 | Returns the type of the page data. |
1006 | Calling this function before the termination of the |
1007 | decoding process might returns <DDJVU_PAGETYPE_UNKNOWN>. */ |
1008 | |
1009 | typedef enum { |
1010 | DDJVU_PAGETYPE_UNKNOWN, |
1011 | DDJVU_PAGETYPE_BITONAL, |
1012 | DDJVU_PAGETYPE_PHOTO, |
1013 | DDJVU_PAGETYPE_COMPOUND, |
1014 | } ddjvu_page_type_t; |
1015 | |
1016 | DDJVUAPI ddjvu_page_type_t |
1017 | ddjvu_page_get_type(ddjvu_page_t *page); |
1018 | |
1019 | |
1020 | /* ddjvu_page_get_{short,long}_description --- DEPRECATED */ |
1021 | |
1022 | DDJVUAPI char *ddjvu_page_get_short_description(ddjvu_page_t *); |
1023 | DDJVUAPI char *ddjvu_page_get_long_description(ddjvu_page_t *); |
1024 | |
1025 | |
1026 | /* ddjvu_page_set_rotation --- |
1027 | Changes the counter-clockwise rotation angle for a DjVu page. |
1028 | Calling this function before receiving a <m_pageinfo> |
1029 | message has no good effect. */ |
1030 | |
1031 | typedef enum { |
1032 | DDJVU_ROTATE_0 = 0, |
1033 | DDJVU_ROTATE_90 = 1, |
1034 | DDJVU_ROTATE_180 = 2, |
1035 | DDJVU_ROTATE_270 = 3, |
1036 | } ddjvu_page_rotation_t; |
1037 | |
1038 | DDJVUAPI void |
1039 | ddjvu_page_set_rotation(ddjvu_page_t *page, |
1040 | ddjvu_page_rotation_t rot); |
1041 | |
1042 | |
1043 | /* ddjvu_page_get_rotation --- |
1044 | Returns the counter-clockwise rotation angle for the DjVu page. |
1045 | The rotation is automatically taken into account |
1046 | by <ddjvu_page_render>, <ddjvu_page_get_width> |
1047 | and <ddjvu_page_get_height>. */ |
1048 | |
1049 | DDJVUAPI ddjvu_page_rotation_t |
1050 | ddjvu_page_get_rotation(ddjvu_page_t *page); |
1051 | |
1052 | |
1053 | /* ddjvu_page_get_initial_rotation --- |
1054 | Returns the page rotation specified by the |
1055 | orientation flags in the DjVu file. |
1056 | [brain damage warning] This is useful because |
1057 | maparea coordinates in the annotation chunks |
1058 | are expressed relative to the rotated coordinates |
1059 | whereas text coordinates in the hidden text data |
1060 | are expressed relative to the unrotated coordinates. */ |
1061 | |
1062 | DDJVUAPI ddjvu_page_rotation_t |
1063 | ddjvu_page_get_initial_rotation(ddjvu_page_t *page); |
1064 | |
1065 | |
1066 | |
1067 | /* ------- RENDER ------- */ |
1068 | |
1069 | |
1070 | /* ddjvu_render_mode_t --- |
1071 | Various ways to render a page. */ |
1072 | |
1073 | typedef enum { |
1074 | DDJVU_RENDER_COLOR = 0, /* color page or stencil */ |
1075 | DDJVU_RENDER_BLACK, /* stencil or color page */ |
1076 | DDJVU_RENDER_COLORONLY, /* color page or fail */ |
1077 | DDJVU_RENDER_MASKONLY, /* stencil or fail */ |
1078 | DDJVU_RENDER_BACKGROUND, /* color background layer */ |
1079 | DDJVU_RENDER_FOREGROUND, /* color foreground layer */ |
1080 | } ddjvu_render_mode_t; |
1081 | |
1082 | |
1083 | /* ddjvu_rect_t --- |
1084 | This structure specifies the location of a rectangle. |
1085 | Coordinates are usually expressed in pixels relative to |
1086 | the BOTTOM LEFT CORNER (but see ddjvu_format_set_y_direction). |
1087 | Members <x> and <y> indicate the position of the bottom left |
1088 | corner of the rectangle Members <w> and <h> indicate the |
1089 | width and height of the rectangle. */ |
1090 | |
1091 | struct ddjvu_rect_s { |
1092 | int x, y; |
1093 | unsigned int w, h; |
1094 | }; |
1095 | |
1096 | |
1097 | /* ddjvu_page_render -- |
1098 | Renders a segment of a page with arbitrary scale. |
1099 | Argument <mode> indicates what image layers |
1100 | should be rendered. |
1101 | |
1102 | Conceptually this function renders the full page |
1103 | into a rectangle <pagerect> and copies the |
1104 | pixels specified by rectangle <renderrect> |
1105 | into the buffer starting at position <imagebuffer>. |
1106 | The actual code is much more efficient than that. |
1107 | |
1108 | The final image is written into buffer <imagebuffer>. |
1109 | Argument <pixelformat> specifies the expected pixel format. |
1110 | Argument <rowsize> specifies the number of BYTES from |
1111 | one row to the next in the buffer. The buffer must be |
1112 | large enough to accomodate the desired image. |
1113 | |
1114 | This function makes a best effort to compute an image |
1115 | that reflects the most recently decoded data. It might |
1116 | return <FALSE> to indicate that no image could be |
1117 | computed at this point, and that nothing was written into |
1118 | the buffer. */ |
1119 | |
1120 | DDJVUAPI int |
1121 | ddjvu_page_render(ddjvu_page_t *page, |
1122 | const ddjvu_render_mode_t mode, |
1123 | const ddjvu_rect_t *, |
1124 | const ddjvu_rect_t *renderrect, |
1125 | const ddjvu_format_t *pixelformat, |
1126 | unsigned long rowsize, |
1127 | char *imagebuffer ); |
1128 | |
1129 | |
1130 | |
1131 | |
1132 | /* -------------------------------------------------- */ |
1133 | /* COORDINATE TRANSFORMS */ |
1134 | /* -------------------------------------------------- */ |
1135 | |
1136 | /* ddjvu_rectmapper_create -- |
1137 | Creates a <ddjvu_rectmapper_t> data structure |
1138 | representing an affine coordinate transformation that |
1139 | maps points from rectangle <input> to rectangle <output>. |
1140 | The transformation maintains the positions relative |
1141 | to the coordinates of the rectangle corners. */ |
1142 | |
1143 | DDJVUAPI ddjvu_rectmapper_t * |
1144 | ddjvu_rectmapper_create(ddjvu_rect_t *input, ddjvu_rect_t *output); |
1145 | |
1146 | |
1147 | /* ddjvu_rectmapper_modify --- |
1148 | Modifies the coordinate transform <mapper> by redefining |
1149 | which corners of the output rectangle match those of the |
1150 | input rectangle. This function first applies a counter-clockwise |
1151 | rotation of <rotation> quarter-turns, and then reverses the X |
1152 | (resp. Y) coordinates when <mirrorx> (resp. <mirrory>) is non zero. */ |
1153 | |
1154 | DDJVUAPI void |
1155 | ddjvu_rectmapper_modify(ddjvu_rectmapper_t *mapper, |
1156 | int rotation, int mirrorx, int mirrory); |
1157 | |
1158 | |
1159 | /* ddjvu_rectmapper_release --- |
1160 | Destroys the <ddjvu_rect_mapper_t> structure |
1161 | returned by <ddjvu_rect_mapper_create>. */ |
1162 | |
1163 | DDJVUAPI void |
1164 | ddjvu_rectmapper_release(ddjvu_rectmapper_t *mapper); |
1165 | |
1166 | /* ddjvu_map_point, ddjvu_map_rect --- |
1167 | Applies the coordinate transform |
1168 | to a point or a rectangle */ |
1169 | |
1170 | DDJVUAPI void |
1171 | ddjvu_map_point(ddjvu_rectmapper_t *mapper, int *x, int *y); |
1172 | |
1173 | DDJVUAPI void |
1174 | ddjvu_map_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect); |
1175 | |
1176 | |
1177 | /* ddjvu_unmap_point, ddjvu_unmap_rect --- |
1178 | Applies the inverse coordinate transform |
1179 | to a point or a rectangle */ |
1180 | |
1181 | DDJVUAPI void |
1182 | ddjvu_unmap_point(ddjvu_rectmapper_t *mapper, int *x, int *y); |
1183 | |
1184 | DDJVUAPI void |
1185 | ddjvu_unmap_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect); |
1186 | |
1187 | |
1188 | |
1189 | |
1190 | /* -------------------------------------------------- */ |
1191 | /* DJVU_FORMAT_T */ |
1192 | /* -------------------------------------------------- */ |
1193 | |
1194 | |
1195 | /* ddjvu_format_style_t --- |
1196 | Enumerated type for pixel formats. */ |
1197 | |
1198 | typedef enum { |
1199 | DDJVU_FORMAT_BGR24, /* truecolor 24 bits in BGR order */ |
1200 | DDJVU_FORMAT_RGB24, /* truecolor 24 bits in RGB order */ |
1201 | DDJVU_FORMAT_RGBMASK16, /* truecolor 16 bits with masks */ |
1202 | DDJVU_FORMAT_RGBMASK32, /* truecolor 32 bits with masks */ |
1203 | DDJVU_FORMAT_GREY8, /* greylevel 8 bits */ |
1204 | DDJVU_FORMAT_PALETTE8, /* paletized 8 bits (6x6x6 color cube) */ |
1205 | DDJVU_FORMAT_MSBTOLSB, /* packed bits, msb on the left */ |
1206 | DDJVU_FORMAT_LSBTOMSB, /* packed bits, lsb on the left */ |
1207 | } ddjvu_format_style_t; |
1208 | |
1209 | |
1210 | /* ddjvu_format_create --- |
1211 | Creates a <ddjvu_format_t> object describing a pixel format. |
1212 | Argument <style> describes the generic pixel format. |
1213 | Argument <args> is an array of <nargs> unsigned ints |
1214 | providing additionnal information: |
1215 | - When style is <RGBMASK*>, argument <nargs> must be <3> or <4>. |
1216 | The three first entries of array <args> are three contiguous |
1217 | bit masks for the red, green, and blue components of each pixel. |
1218 | The resulting color is then xored with the optional fourth entry. |
1219 | - When style is <PALETTE*>, argument <nargs> must be <216> |
1220 | and array <args> contains the 6*6*6 entries of a web |
1221 | color cube. |
1222 | - Otherwise <nargs> must be <0>. */ |
1223 | |
1224 | DDJVUAPI ddjvu_format_t * |
1225 | ddjvu_format_create(ddjvu_format_style_t style, |
1226 | int nargs, unsigned int *args); |
1227 | |
1228 | |
1229 | /* ddjvu_format_set_row_order --- |
1230 | Sets a flag indicating whether the rows in the pixel buffer |
1231 | are stored starting from the top or the bottom of the image. |
1232 | Default ordering starts from the bottom of the image. |
1233 | This is the opposite of the X11 convention. */ |
1234 | |
1235 | DDJVUAPI void |
1236 | ddjvu_format_set_row_order(ddjvu_format_t *format, int top_to_bottom); |
1237 | |
1238 | |
1239 | /* ddjvu_format_set_y_direction --- |
1240 | Sets a flag indicating whether the y coordinates in the drawing |
1241 | area are oriented from bottom to top, or from top to botttom. |
1242 | The default is bottom to top, similar to PostScript. |
1243 | This is the opposite of the X11 convention. */ |
1244 | |
1245 | DDJVUAPI void |
1246 | ddjvu_format_set_y_direction(ddjvu_format_t *format, int top_to_bottom); |
1247 | |
1248 | |
1249 | /* ddjvu_format_set_ditherbits --- |
1250 | Specifies the final depth of the image on the screen. |
1251 | This is used to decide which dithering algorithm should be used. |
1252 | The default is usually appropriate. */ |
1253 | |
1254 | DDJVUAPI void |
1255 | ddjvu_format_set_ditherbits(ddjvu_format_t *format, int bits); |
1256 | |
1257 | |
1258 | /* ddjvu_format_set_gamma --- |
1259 | Sets the gamma of the display for which the pixels are |
1260 | intended. This will be combined with the gamma stored in |
1261 | DjVu documents in order to compute a suitable color |
1262 | correction. The default value is 2.2. */ |
1263 | |
1264 | DDJVUAPI void |
1265 | ddjvu_format_set_gamma(ddjvu_format_t *format, double gamma); |
1266 | |
1267 | |
1268 | /* ddjvu_format_set_white --- |
1269 | Sets the whitepoint of the display for which the pixels are |
1270 | intended. This will be combined with the gamma stored in |
1271 | DjVu documents in order to compute a suitable color |
1272 | correction. The default value is 0xff,0xff,0xff. */ |
1273 | |
1274 | DDJVUAPI void |
1275 | ddjvu_format_set_white(ddjvu_format_t *format, |
1276 | unsigned char b, unsigned char g, unsigned char r); |
1277 | |
1278 | /* ddjvu_format_release --- |
1279 | Release a reference to a <ddjvu_format_t> object. |
1280 | The calling program should no longer reference this object. */ |
1281 | |
1282 | DDJVUAPI void |
1283 | ddjvu_format_release(ddjvu_format_t *format); |
1284 | |
1285 | |
1286 | |
1287 | |
1288 | /* -------------------------------------------------- */ |
1289 | /* THUMBNAILS */ |
1290 | /* -------------------------------------------------- */ |
1291 | |
1292 | |
1293 | /* ddjvu_thumbnail_status --- |
1294 | Determine whether a thumbnail is available for page <pagenum>. |
1295 | Calling this function with non zero argument <start> initiates |
1296 | a thumbnail calculation job. Regardless of its success, |
1297 | the completion of the job is signalled by a subsequent |
1298 | <m_thumbnail> message. */ |
1299 | |
1300 | DDJVUAPI ddjvu_status_t |
1301 | ddjvu_thumbnail_status(ddjvu_document_t *document, int pagenum, int start); |
1302 | |
1303 | |
1304 | /* ddjvu_message_t::m_thumbnail --- |
1305 | This message is sent when additional thumbnails are available. */ |
1306 | |
1307 | struct ddjvu_message_thumbnail_s { /* ddjvu_message_t::m_thumbnail */ |
1308 | ddjvu_message_any_t any; |
1309 | int pagenum; |
1310 | }; |
1311 | |
1312 | |
1313 | /* ddjvu_thumbnail_render --- |
1314 | Renders a thumbnail for page <pagenum>. |
1315 | Argument <imagebuffer> must be large enough to contain |
1316 | an image of size <*wptr> by <*hptr> using pixel format |
1317 | <pixelformat>. Argument <rowsize> specifies the number |
1318 | of BYTES from one row to the next in the buffer. |
1319 | This function returns <FALSE> when no thumbnail is available. |
1320 | Otherwise it returns <TRUE>, adjusts <*wptr> and <*hptr> to |
1321 | reflect the thumbnail size, and, if the pointer <imagebuffer> |
1322 | is non zero, writes the pixel data into the image buffer. */ |
1323 | |
1324 | DDJVUAPI int |
1325 | ddjvu_thumbnail_render(ddjvu_document_t *document, int pagenum, |
1326 | int *wptr, int *hptr, |
1327 | const ddjvu_format_t *pixelformat, |
1328 | unsigned long rowsize, |
1329 | char *imagebuffer); |
1330 | |
1331 | |
1332 | |
1333 | /* -------------------------------------------------- */ |
1334 | /* SAVE AND PRINT JOBS */ |
1335 | /* -------------------------------------------------- */ |
1336 | |
1337 | |
1338 | /* ddjvu_message_t::m_progress --- |
1339 | These messages are generated to indicate progress |
1340 | towards the completion of a print or save job. */ |
1341 | |
1342 | struct ddjvu_message_progress_s { |
1343 | ddjvu_message_any_t any; |
1344 | ddjvu_status_t status; |
1345 | int percent; |
1346 | }; |
1347 | |
1348 | /* ddjvu_document_print --- |
1349 | Converts specified pages of a djvu document into postscript. |
1350 | This function works asynchronously in a separate thread. |
1351 | You can use the following idiom for synchronous operation: |
1352 | |
1353 | ddjvu_job_t *job = ddjvu_document_print(....); |
1354 | while (! ddjvu_job_done(job) ) |
1355 | handle_ddjvu_messages(context, TRUE); |
1356 | |
1357 | The postscript data is written to stdio file <output>. |
1358 | Arguments <optc> and <optv> specify printing options. |
1359 | All options described on the <djvups> man page are |
1360 | recognized, except <"-help"> and <"-verbose">. |
1361 | */ |
1362 | |
1363 | DDJVUAPI ddjvu_job_t * |
1364 | ddjvu_document_print(ddjvu_document_t *document, FILE *output, |
1365 | int optc, const char * const * optv); |
1366 | |
1367 | |
1368 | /* ddjvu_document_save --- |
1369 | Saves the djvu document as a bundled djvu file. |
1370 | This function works asynchronously in a separate thread. |
1371 | You can use the following idiom for synchronous operation: |
1372 | |
1373 | ddjvu_job_t *job = ddjvu_document_save(....); |
1374 | while (! ddjvu_job_done(job) ) |
1375 | handle_ddjvu_messages(context, TRUE); |
1376 | |
1377 | The bundled djvu data is written to file <output> |
1378 | which must be seekable. Arguments <optc> and <optv> |
1379 | can be used to pass the following options: |
1380 | * Option "-pages=<pagespec>" specify a subset of pages |
1381 | using the same syntax as program <ddjvu>. |
1382 | Reordering or duplicating pages is prohibited. |
1383 | * Option "-indirect=<filename>" causes the creation |
1384 | of an indirect document with index file <filename> |
1385 | and auxiliary files in the same directory. |
1386 | The file name is UTF-8 encoded. |
1387 | When this option is specified, the argument <output> |
1388 | is ignored and should be NULL. |
1389 | */ |
1390 | DDJVUAPI ddjvu_job_t * |
1391 | ddjvu_document_save(ddjvu_document_t *document, FILE *output, |
1392 | int optc, const char * const * optv); |
1393 | |
1394 | |
1395 | |
1396 | |
1397 | /* -------------------------------------------------- */ |
1398 | /* S-EXPRESSIONS */ |
1399 | /* -------------------------------------------------- */ |
1400 | |
1401 | |
1402 | /* DjVu files can contain ancillary information such as |
1403 | document outline, hidden text, hyperlinks, and metadata. |
1404 | Program <djvused> provides for manipulating such |
1405 | information. Like <djvused>, the DDJVU API represents |
1406 | this information using a lisp s-expressions. See file |
1407 | <"libdjvu/miniexp.h"> for the s-expression documentation |
1408 | and manipulation functions. See the <djvused> man page |
1409 | for the specification of the s-expressions representing |
1410 | outlines, hidden text and annotations. It often help |
1411 | to print s-expressions using function <miniexp_pprint>. |
1412 | |
1413 | WARNING: All strings in s-expression are UTF-8 encoded. |
1414 | Strings returned by miniexp_to_str might have to be |
1415 | converted to the locale encoding. */ |
1416 | |
1417 | |
1418 | /* miniexp_t -- |
1419 | Opaque type representing s-expressions. |
1420 | The same definition also appears in |
1421 | file <"libdjvu/miniexp.h">. */ |
1422 | |
1423 | #ifndef MINIEXP_H |
1424 | typedef struct miniexp_s* miniexp_t; |
1425 | #endif |
1426 | |
1427 | /* ddjvu_miniexp_release -- |
1428 | This function controls the allocation of the |
1429 | s-expressions returned by functions from the DDJVU |
1430 | API. It indicates that the s-expression <expr> is no |
1431 | longer needed and can be deallocated as soon as |
1432 | necessary. Otherwise the s-expression remains allocated |
1433 | as long as the document object exists. */ |
1434 | |
1435 | DDJVUAPI void |
1436 | ddjvu_miniexp_release(ddjvu_document_t *document, miniexp_t expr); |
1437 | |
1438 | |
1439 | /* ddjvu_document_get_outline -- |
1440 | This function tries to obtain the document outline. |
1441 | If this information is available, it returns a |
1442 | s-expression with the same syntax as function |
1443 | <print-outline> of program <djvused>. |
1444 | Otherwise it returns <miniexp_dummy> until |
1445 | the document header gets fully decoded. |
1446 | Typical synchronous usage: |
1447 | |
1448 | miniexp_t r; |
1449 | while ((r=ddjvu_document_get_outline(doc))==miniexp_dummy) |
1450 | handle_ddjvu_messages(ctx, TRUE); |
1451 | |
1452 | This function returns the empty list <miniexp_nil> when |
1453 | the document contains no outline information. It can also |
1454 | return symbols <failed> or <stopped> when an error occurs |
1455 | while accessing the desired information. */ |
1456 | |
1457 | DDJVUAPI miniexp_t |
1458 | ddjvu_document_get_outline(ddjvu_document_t *document); |
1459 | |
1460 | |
1461 | /* ddjvu_document_get_anno -- |
1462 | This function returns the document-wide annotations. |
1463 | This corresponds to a proposed change in the djvu format. |
1464 | When no new-style document-wide annotations are available |
1465 | and <compat> is true, this function searches a shared |
1466 | annotation chunk and returns its contents. |
1467 | |
1468 | This function returns <miniexp_dummy> if the information |
1469 | is not yet available. It may then cause the emission |
1470 | of <m_pageinfo> messages with null <m_any.page>. |
1471 | |
1472 | This function returns the empty list <miniexp_nil> when |
1473 | the document does not contain page annotations. It can also |
1474 | return symbols <failed> or <stopped> when an error occurs |
1475 | while accessing the desired information. */ |
1476 | |
1477 | DDJVUAPI miniexp_t |
1478 | ddjvu_document_get_anno(ddjvu_document_t *document, int compat); |
1479 | |
1480 | |
1481 | /* ddjvu_document_get_pagetext -- |
1482 | This function tries to obtain the text information for |
1483 | page <pageno>. If this information is available, it |
1484 | returns a s-expression with the same syntax as function |
1485 | <print-txt> of program <djvused>. Otherwise it starts |
1486 | fetching the page data and returns <miniexp_dummy>. |
1487 | This function causes the emission of <m_pageinfo> messages |
1488 | with zero in the <m_any.page> field. |
1489 | Typical synchronous usage: |
1490 | |
1491 | miniexp_t r; |
1492 | while ((r=ddjvu_document_get_pagetext(doc,pageno,0))==miniexp_dummy) |
1493 | handle_ddjvu_messages(ctx, TRUE); |
1494 | |
1495 | This function returns the empty list <miniexp_nil> when |
1496 | the page contains no text information. It can also return |
1497 | symbols <failed> or <stopped> when an error occurs while |
1498 | accessing the desired information. |
1499 | |
1500 | Argument <maxdetail> controls the level of detail in the |
1501 | returned s-expression. Values "page", "column", "region", "para", |
1502 | "line", and "word" restrict the output to the specified granularity. |
1503 | All other values produce a s-expression that represents |
1504 | the hidden text data as finely as possible. */ |
1505 | |
1506 | DDJVUAPI miniexp_t |
1507 | ddjvu_document_get_pagetext(ddjvu_document_t *document, int pageno, |
1508 | const char *maxdetail); |
1509 | |
1510 | |
1511 | /* ddjvu_document_get_pageanno -- |
1512 | This function tries to obtain the annotations for |
1513 | page <pageno>. If this information is available, it |
1514 | returns a s-expression with the same syntax as function |
1515 | <print-ant> of program <djvused>. Otherwise it starts |
1516 | fetching the page data and returns <miniexp_dummy>. |
1517 | This function causes the emission of <m_pageinfo> messages |
1518 | with zero in the <m_any.page> field. |
1519 | Typical synchronous usage: |
1520 | |
1521 | miniexp_t r; |
1522 | while ((r = ddjvu_document_get_pageanno(doc,pageno))==miniexp_dummy) |
1523 | handle_ddjvu_messages(ctx, TRUE); |
1524 | |
1525 | This function returns the empty list <miniexp_nil> when |
1526 | the page contains no annotations. It can also return |
1527 | symbols <failed> or <stopped> when an error occurs while |
1528 | accessing the desired information. */ |
1529 | |
1530 | DDJVUAPI miniexp_t |
1531 | ddjvu_document_get_pageanno(ddjvu_document_t *document, int pageno); |
1532 | |
1533 | |
1534 | /* --- Helper functions to parse annotations --- */ |
1535 | |
1536 | /* ddjvu_anno_get_bgcolor -- |
1537 | Parse the annotations and extracts the desired |
1538 | background color as a color string ("#FFFFFF"). |
1539 | See <(background ...)> in the djvused man page. |
1540 | Returns zero if this information is not specified. */ |
1541 | |
1542 | DDJVUAPI const char * |
1543 | ddjvu_anno_get_bgcolor(miniexp_t annotations); |
1544 | |
1545 | |
1546 | /* ddjvu_anno_get_zoom -- |
1547 | Parse the annotations and extracts the desired zoom factor. |
1548 | See <(zoom ...)> in the djvused man page. |
1549 | Returns zero if this information is not specified. */ |
1550 | |
1551 | DDJVUAPI const char * |
1552 | ddjvu_anno_get_zoom(miniexp_t annotations); |
1553 | |
1554 | |
1555 | /* ddjvu_anno_get_mode -- |
1556 | Parse the annotations and extracts the desired display mode. |
1557 | See <(mode ...)> in the djvused man page. |
1558 | Returns zero if this information is not specified. */ |
1559 | |
1560 | DDJVUAPI const char * |
1561 | ddjvu_anno_get_mode(miniexp_t annotations); |
1562 | |
1563 | |
1564 | /* ddjvu_anno_get_horizalign -- |
1565 | Parse the annotations and extracts how the page |
1566 | image should be aligned horizontally. |
1567 | See <(align ...)> in the djvused man page. |
1568 | Returns zero if this information is not specified. */ |
1569 | |
1570 | DDJVUAPI const char * |
1571 | ddjvu_anno_get_horizalign(miniexp_t annotations); |
1572 | |
1573 | |
1574 | /* ddjvu_anno_get_vertalign -- |
1575 | Parse the annotations and extracts how the page |
1576 | image should be aligned vertically. |
1577 | See <(align ...)> in the djvused man page. |
1578 | Returns zero if this information is not specified. */ |
1579 | |
1580 | DDJVUAPI const char * |
1581 | ddjvu_anno_get_vertalign(miniexp_t annotations); |
1582 | |
1583 | |
1584 | /* ddjvu_anno_get_hyperlinks -- |
1585 | Parse the annotations and returns a zero terminated |
1586 | array of <(maparea ...)> s-expressions. |
1587 | The caller should free this array with function <free>. |
1588 | These s-expressions remain allocated as long |
1589 | as the annotations remain allocated. |
1590 | See also <(maparea ...)> in the djvused man page. */ |
1591 | |
1592 | DDJVUAPI miniexp_t * |
1593 | ddjvu_anno_get_hyperlinks(miniexp_t annotations); |
1594 | |
1595 | |
1596 | /* ddjvu_anno_get_metadata_keys -- |
1597 | Parse the annotations and returns a zero terminated |
1598 | array of key symbols for the page metadata. |
1599 | The caller should free this array with function <free>. |
1600 | See also <(metadata ...)> in the djvused man page. */ |
1601 | |
1602 | DDJVUAPI miniexp_t * |
1603 | ddjvu_anno_get_metadata_keys(miniexp_t annotations); |
1604 | |
1605 | |
1606 | /* ddjvu_anno_get_metadata -- |
1607 | Parse the annotations and returns the metadata string |
1608 | corresponding to the metadata key symbol <key>. |
1609 | The string remains allocated as long as the |
1610 | annotations s-expression remain allocated. |
1611 | Returns zero if no such key is present. */ |
1612 | |
1613 | DDJVUAPI const char * |
1614 | ddjvu_anno_get_metadata(miniexp_t annotations, miniexp_t key); |
1615 | |
1616 | |
1617 | /* ddjvu_anno_get_xmp -- |
1618 | Parse the annotations and returns the xmp metadata string. |
1619 | The string remains allocated as long as the |
1620 | annotations s-expression remain allocated. |
1621 | Returns zero if no such key is present. */ |
1622 | |
1623 | DDJVUAPI const char * |
1624 | ddjvu_anno_get_xmp(miniexp_t annotations); |
1625 | |
1626 | |
1627 | /* -------------------------------------------------- */ |
1628 | /* DJVU_MESSAGE_T */ |
1629 | /* -------------------------------------------------- */ |
1630 | |
1631 | |
1632 | /* We can now define the djvu_message_t union */ |
1633 | |
1634 | union ddjvu_message_s { |
1635 | struct ddjvu_message_any_s m_any; |
1636 | struct ddjvu_message_error_s m_error; |
1637 | struct ddjvu_message_info_s m_info; |
1638 | struct ddjvu_message_newstream_s m_newstream; |
1639 | struct ddjvu_message_docinfo_s m_docinfo; |
1640 | struct ddjvu_message_pageinfo_s m_pageinfo; |
1641 | struct ddjvu_message_chunk_s m_chunk; |
1642 | struct ddjvu_message_relayout_s m_relayout; |
1643 | struct ddjvu_message_redisplay_s m_redisplay; |
1644 | struct ddjvu_message_thumbnail_s m_thumbnail; |
1645 | struct ddjvu_message_progress_s m_progress; |
1646 | }; |
1647 | |
1648 | |
1649 | /* -------------------------------------------------- */ |
1650 | /* BACKDOORS */ |
1651 | /* -------------------------------------------------- */ |
1652 | |
1653 | #ifdef __cplusplus |
1654 | } // extern "C" |
1655 | #endif |
1656 | |
1657 | /* ddjvu_get_DjVuImage --- |
1658 | ddjvu_get_DjVuDocument --- |
1659 | These functions provide an access to the libdjvu objects |
1660 | associated with the ddjvuapi objects. These backdoors can |
1661 | be useful for advanced manipulations. These two functions |
1662 | are declared in C++ when file <"ddjvuapi.h"> is included |
1663 | after the libdjvu header files <"DjVuImage.h"> and |
1664 | <"DjVuDocument.h">. */ |
1665 | |
1666 | #ifdef __cplusplus |
1667 | # ifndef NOT_USING_DJVU_NAMESPACE |
1668 | # ifdef _DJVUIMAGE_H |
1669 | DDJVUAPI GP<DjVuImage> |
1670 | ddjvu_get_DjVuImage(ddjvu_page_t *page); |
1671 | # endif |
1672 | # ifdef _DJVUDOCUMENT_H |
1673 | DDJVUAPI GP<DjVuDocument> |
1674 | ddjvu_get_DjVuDocument(ddjvu_document_t *document); |
1675 | # endif |
1676 | # endif |
1677 | #endif |
1678 | |
1679 | #endif /* DDJVUAPI_H */ |
1680 | |