File: ddjvuapi.h

package info (click to toggle)
djvulibre 3.5.27.1-10
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 9,664 kB
  • sloc: cpp: 65,465; xml: 5,723; ansic: 4,936; sh: 865; makefile: 316
file content (1688 lines) | stat: -rw-r--r-- 56,955 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
/* 
//C- -------------------------------------------------------------------
//C- DjVuLibre-3.5
//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
//C- Copyright (c) 2001  AT&T
//C-
//C- This software is subject to, and may be distributed under, the
//C- GNU General Public License, either Version 2 of the license,
//C- or (at your option) any later version. The license should have
//C- accompanied the software or you may obtain a copy of the license
//C- from the Free Software Foundation at http://www.fsf.org .
//C-
//C- This program is distributed in the hope that it will be useful,
//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//C- GNU General Public License for more details.
//C- 
//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
//C- Lizardtech Software.  Lizardtech Software has authorized us to
//C- replace the original DjVu(r) Reference Library notice by the following
//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
//C-
//C-  ------------------------------------------------------------------
//C- | DjVu (r) Reference Library (v. 3.5)
//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
//C- | The DjVu Reference Library is protected by U.S. Pat. No.
//C- | 6,058,214 and patents pending.
//C- |
//C- | This software is subject to, and may be distributed under, the
//C- | GNU General Public License, either Version 2 of the license,
//C- | or (at your option) any later version. The license should have
//C- | accompanied the software or you may obtain a copy of the license
//C- | from the Free Software Foundation at http://www.fsf.org .
//C- |
//C- | The computer code originally released by LizardTech under this
//C- | license and unmodified by other parties is deemed "the LIZARDTECH
//C- | ORIGINAL CODE."  Subject to any third party intellectual property
//C- | claims, LizardTech grants recipient a worldwide, royalty-free, 
//C- | non-exclusive license to make, use, sell, or otherwise dispose of 
//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the 
//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU 
//C- | General Public License.   This grant only confers the right to 
//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to 
//C- | the extent such infringement is reasonably necessary to enable 
//C- | recipient to make, have made, practice, sell, or otherwise dispose 
//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to 
//C- | any greater extent that may be necessary to utilize further 
//C- | modifications or combinations.
//C- |
//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
//C- +------------------------------------------------------------------
*/

#ifndef DDJVUAPI_H
#define DDJVUAPI_H

#ifdef __cplusplus
extern "C" { 
#endif
#if 0
}
#endif

#include <stddef.h>
#include <stdlib.h>
#include <stdio.h>

#ifndef DDJVUAPI
# ifdef _WIN32
#  ifdef DDJVUAPI_EXPORT
#   define DDJVUAPI __declspec(dllexport)
#  else
#   define DDJVUAPI __declspec(dllimport)
#  endif
# endif
#endif
#ifndef DDJVUAPI
# define DDJVUAPI /**/
#endif

#ifndef TRUE
# define TRUE  (1)
#endif

#ifndef FALSE
# define FALSE (0)
#endif



/* -------------------------------------------------- */
/* DDJVU API                                          */
/* -------------------------------------------------- */

/* The DDJVU API provides for efficiently decoding and
   displaying DjVu documents.  It provides for displaying
   images without waiting for the complete DjVu data. Images
   can be displayed as soon as sufficient data is
   available. A higher quality image might later be
   displayed when further data is available.  The DjVu
   library achieves this using a complicated scheme
   involving multiple threads. The DDJVU API hides this
   complexity with a familiar event model.
*/

/* Compiler symbol DDJVUAPI_VERSION tracks 
   backward compatible additions to the DDJVU API.

   Version   Change
   -----------------------------
     24    Added:
              miniexp_lstring()
              miniexp_to_lstr()
     23    Added:
              miniexp_mutate()
     22    Changed
              miniexp strings accept unicode escapes
              deprecated miniexp_io_t::p_print7bits
              added miniexp_io_t::p_flags
     21    Added:
              reentrant version of miniexp input/output
     20    Added:
              ddjvu_get_version_string()
              ddjvu_format_set_white()
              ddjvu_anno_get_xmp()
     19    Added:
              ddjvu_document_create_by_filename_utf8()
     18    Added:
              ddjvu_document_get_{anno,pagedump,filedump}()
           Modifed (binary compatible):
              ddjvu_document_get_{fileinfo,pageinfo}()   
              ddjvu_document_save() [--pages, --indirect=]
           Deprecated:
              ddjvu_document_search_pageno()
              ddjvu_page_get_{short,long}_description()
     17    Added:
              ddjvu_page_get_initial_rotation(), ddjvu_code_get_version()
              ddjvu_document_{get_filenum,get_fileinfo}}()
              ddjvu_document_{search_pageno,check_pagedata}()
              ddjvu_rectmapper_t and related functions.
     16    Added:
              miniexp.h and related functions.
     15    Added:
              ddjvu_document_get_pageinfo()
              ddjvu_document_print()
     14    Initial version.
*/

#define DDJVUAPI_VERSION 23

typedef struct ddjvu_context_s    ddjvu_context_t;
typedef union  ddjvu_message_s    ddjvu_message_t;
typedef struct ddjvu_job_s        ddjvu_job_t;
typedef struct ddjvu_document_s   ddjvu_document_t;
typedef struct ddjvu_page_s       ddjvu_page_t;
typedef struct ddjvu_format_s     ddjvu_format_t;
typedef struct ddjvu_rect_s       ddjvu_rect_t;
typedef struct ddjvu_rectmapper_s ddjvu_rectmapper_t;


/* GENERAL CONVENTIONS:

   - all strings use locale encoding (unless specified otherwise).
   - all filenames are unencoded byte strings,
   - all errors are signaled with error event messages,
   - all functions returning a pointer might return a null pointer.

   HEADER:
   Always use the following idiom to include this file.

     #include <libdjvu/ddjvuapi.h>
     #include <libdjvu/miniexp.h>

   This file does not declare functions ddjvu_get_DjVuImage() 
   and djvu_get_DjVuDocument() unless you include files 
   "DjVuImage.h" and "DjVuDocument.h" before this file.

   PREREQUISITES:
   - Please read the djvu man page: <"tools/djvu.1">.
   - Please browse the file format specifications 
     <"doc/djvu3changes.txt"> and <"doc/djvu3spec.djvu">.
*/

  

/* -------------------------------------------------- */
/* DDJVU_CONTEXT_T                                    */
/* -------------------------------------------------- */

/* There is usually only one <ddjvu_context_t> object.  
   This object holds global data structures such as the 
   cache of decoded pages, or the list of pending 
   event messages.
 */



/* ddjvu_get_version_string() ---
   Returns a string that described the underlying code. */

DDJVUAPI const char*
ddjvu_get_version_string(void);


/* ddjvu_context_create ---
   Creates a <ddjvu_context_t> object.
   Argument <programname> is the name of the calling executable. */

DDJVUAPI ddjvu_context_t *
ddjvu_context_create(const char *programname);


/* ddjvu_context_release ---
   Release a reference to a <ddjvu_context_t> object.
   The calling program should no longer reference this object.
   The object itself will be destroyed as soon as no other object
   or thread needs it. */

DDJVUAPI void 
ddjvu_context_release(ddjvu_context_t *context);





/* ------- CACHE ------- */

/* ddjvu_cache_set_size ---
   Sets the maximum size of the cache of decoded page data.
   The argument is expressed in bytes. */

DDJVUAPI void
ddjvu_cache_set_size(ddjvu_context_t *context,
                     unsigned long cachesize);


/* ddjvu_cache_get_size ---
   Returns the maximum size of the cache. */

DDJVUAPI unsigned long
ddjvu_cache_get_size(ddjvu_context_t *context);


/* ddjvu_cache_clear ---
   Clears all cached data. */

DDJVUAPI void
ddjvu_cache_clear(ddjvu_context_t *context);



/* ------- MESSAGE QUEUE ------- */

/* Messages produced by the ddjvu api accumulate into
   the message queue. Processing messages is not optional!
   A typical message handling routine looks like this:
   
   void handle_ddjvu_messages(ddjvu_context_t *ctx, int wait)
   {
     const ddjvu_message_t *msg;
     if (wait)
       ddjvu_message_wait(ctx);
     while ((msg = ddjvu_message_peek(ctx)))
     {
       switch(msg->m_any.tag)
       { 
       case DDJVU_ERROR:      .... ; break;
       case DDJVU_INFO:       .... ; break;
       case DDJVU_NEWSTREAM:  .... ; break;
       ....
       default: break;
       }
       ddjvu_message_pop(ctx);
     }
   }
*/


/* ddjvu_message_peek ---
   Returns a pointer to the next DDJVU message.
   This function returns 0 if no message is available.
   It does not remove the message from the queue. */

DDJVUAPI ddjvu_message_t *
ddjvu_message_peek(ddjvu_context_t *context);


/* ddjvu_message_wait ---
   Returns a pointer to the next DDJVU message.
   This function waits until a message is available.
   It does not remove the message from the queue. */

DDJVUAPI ddjvu_message_t *
ddjvu_message_wait(ddjvu_context_t *context);


/* ddjvu_message_pop ---
   Removes one message from the queue.
   This function must be called after processing the message.
   Pointers returned by previous calls to <ddjvu_message_peek> 
   or <ddjvu_message_wait> are no longer valid after 
   calling <ddjvu_message_pop>. */

DDJVUAPI void
ddjvu_message_pop(ddjvu_context_t *context);


/* ddjvu_message_set_callback ---
   Defines a callback function invoked whenever
   a new message is posted to the ddjvuapi message queue,
   and returns a pointer to the previous callback function.
   This callback function can be called at any time
   while other code is executing. Do not call ddjvuapi
   functions from this callback. It should simply signal
   the main application event loop that new ddjvuapi messages
   are available.  Under WIN32, this is usually achieved
   by posting a user window message.  Under UNIX, this is
   usually achieved using a pipe: the callback writes 
   a single byte into the pipe; the main application loop
   monitors the reading end of the pipe and detects
   the presence of data. */

typedef void 
(*ddjvu_message_callback_t)(ddjvu_context_t *context, void *closure);

DDJVUAPI void
ddjvu_message_set_callback(ddjvu_context_t *context,
                           ddjvu_message_callback_t callback,
                           void *closure);



/* -------------------------------------------------- */
/* DDJVU_JOB_T                                        */
/* -------------------------------------------------- */


/* Many essential ddjvuapi functions initiate asynchronous operations. 
   These "jobs" run in seperate threads and report their
   progress by posting messages into the ddjvu context event queue. 
   Jobs are sometimes represented by a ddjvu_job_t object. */

/* ddjvu_job_status ---
   Returns the status of the specified job. */

typedef enum {
  DDJVU_JOB_NOTSTARTED, /* operation was not even started */
  DDJVU_JOB_STARTED,    /* operation is in progress */
  DDJVU_JOB_OK,         /* operation terminated successfully */
  DDJVU_JOB_FAILED,     /* operation failed because of an error */
  DDJVU_JOB_STOPPED     /* operation was interrupted by user */
} ddjvu_status_t;

DDJVUAPI ddjvu_status_t
ddjvu_job_status(ddjvu_job_t *job);

#define ddjvu_job_done(job) \
    (ddjvu_job_status(job) >= DDJVU_JOB_OK)
#define ddjvu_job_error(job) \
    (ddjvu_job_status(job) >= DDJVU_JOB_FAILED)


/* ddjvu_job_stop ---
   Attempts to cancel the specified job.
   This is a best effort function. 
   There no guarantee that the job will 
   actually stop.
 */

DDJVUAPI void
ddjvu_job_stop(ddjvu_job_t *job);


/* ddjvu_job_set_user_data ---
   ddjvu_job_get_user_data ---
   Each job can store an arbitrary pointer
   that callers can use for any purpose. These two 
   functions provide for accessing or setting this pointer. 
   This pointer is cleared when the job is released */

DDJVUAPI void
ddjvu_job_set_user_data(ddjvu_job_t *job, void *userdata);

DDJVUAPI void *
ddjvu_job_get_user_data(ddjvu_job_t *job);


/* ddjvu_job_release ---
   Releases a reference to a job object and clears its user 
   data field.  This does not cause the job to stop executing.
   The calling program should no longer reference this object.
   The object itself will be destroyed as soon as no 
   other object or thread needs it. 
*/

DDJVUAPI void
ddjvu_job_release(ddjvu_job_t *job);



/* -------------------------------------------------- */
/* DDJVU_MESSAGE_T                                    */
/* -------------------------------------------------- */


/* ddjvu_message_t ---
   This union type represents messages delivered by the
   DDJVU API. Each member of the union pertains to a
   specific kind of message.  Member <m_any> represents the
   information common to all kinds of messages.  Given a
   pointer <p> to a <djvu_message_t>, the message kind can
   be accessed as <"p->m_any.tag">. */


/* ddjvu_message_tag_t ---
   This enumerated type identifies each kind of 
   message delivered by the DDJVU API.  */

typedef enum {
  DDJVU_ERROR,
  DDJVU_INFO,
  DDJVU_NEWSTREAM,
  DDJVU_DOCINFO,
  DDJVU_PAGEINFO,
  DDJVU_RELAYOUT,
  DDJVU_REDISPLAY,
  DDJVU_CHUNK,
  DDJVU_THUMBNAIL,
  DDJVU_PROGRESS,
} ddjvu_message_tag_t;


/* ddjvu_message_t::m_any ---
   This structure is a member of the union <djvu_message_t>.
   It represents the information common to all kinds of
   messages.  Member <tag> indicates the kind of message.
   Members <context>, <document>, <page>, and <job> indicate 
   the origin of the message.  These fields contain null
   pointers when they are not relevant.
   These fields are also cleared when the corresponding
   object is released with <ddjvu_{job,page,document}_release>.
   If the message has not yet been passed to the user 
   with <ddjvu_message_{peek,wait}>, it is silently 
   removed from the message queue. */

typedef struct ddjvu_message_any_s {
  ddjvu_message_tag_t   tag;
  ddjvu_context_t      *context;
  ddjvu_document_t     *document;
  ddjvu_page_t         *page;
  ddjvu_job_t          *job;
} ddjvu_message_any_t; 


/* ddjvu_message_t::m_error ---
   Error messages are generated whenever the decoder or the
   DDJVU API encounters an error condition.  All errors are
   reported as error messages because they can occur
   asynchronously.  Member <message> is the error message.
   Members <function>, <filename> and <lineno>
   indicates the place where the error was detected. */

struct ddjvu_message_error_s {  /* ddjvu_message_t::m_error */
  ddjvu_message_any_t   any;
  const char           *message;
  const char           *function;
  const char           *filename;
  int                   lineno;
}; 


/* ddjvu_message_t::m_info ---
   This messages provides informational text indicating
   the progress of the decoding process. This might
   be displayed in the browser status bar. */

struct ddjvu_message_info_s {   /* ddjvu_message_t::m_info */
  ddjvu_message_any_t  any;
  const char          *message;
}; 




/* -------------------------------------------------- */
/* DDJVU_DOCUMENT_T                                    */
/* -------------------------------------------------- */


/* ddjvu_document_create ---
   Creates a decoder for a DjVu document and starts
   decoding.  This function returns immediately.  The
   decoding job then generates messages to request the raw
   data and to indicate the state of the decoding process.

   Argument <url> specifies an optional URL for the document.  
   The URL follows the usual syntax (<"protocol://machine/path">). 
   It should not end with a slash. It only serves two purposes:
   - The URL is used as a key for the cache of decoded pages.
   - The URL is used to document <m_newstream> messages.

   Setting argument <cache> to <TRUE> indicates that decoded pages
   should be cached when possible.  This only works when
   argument <url> is not the null pointer.

   It is important to understand that the URL is not used to
   access the data.  The document generates <m_newstream>
   messages to indicate which data is needed.  The caller must 
   then provide the raw data using <ddjvu_stream_write> 
   and <ddjvu_stream_close>.

   Localized characters in argument <url> should be in 
   urlencoded UTF-8 (like "%2A"). What is happening for non 
   ascii characters is unclear (probably UTF-8). */

DDJVUAPI ddjvu_document_t *
ddjvu_document_create(ddjvu_context_t *context,
                      const char *url,
                      int cache);


/* ddjvu_document_create_by_filename ---
   Creates a document for a DjVu document stored in a file.
   The document will directly access the specified DjVu file 
   or related files without generating <m_newstream> messages.
   The standard function expects the filename in locale encoding. 
   The utf8 variant expects an utf8 encoded filename. */

DDJVUAPI ddjvu_document_t *
ddjvu_document_create_by_filename(ddjvu_context_t *context,
                                  const char *filename,
                                  int cache);

DDJVUAPI ddjvu_document_t *
ddjvu_document_create_by_filename_utf8(ddjvu_context_t *context,
                                       const char *filename,
                                       int cache);

/* ddjvu_document_job ---
   Access the job object in charge of decoding the document header. 
   In fact <ddjvu_document_t> is a subclass of <ddjvu_job_t>
   and this function is a type cast. */

DDJVUAPI ddjvu_job_t *
ddjvu_document_job(ddjvu_document_t *document);


/* ddjvu_document_release ---
   Release a reference to a <ddjvu_document_t> object.
   The calling program should no longer reference this object.  
   The object itself will be destroyed as soon as no other object
   or thread needs it. */
 
#define ddjvu_document_release(document) \
   ddjvu_job_release(ddjvu_document_job(document))


/* ddjvu_document_set_user_data ---
   ddjvu_document_get_user_data ---
   Each <ddjvu_document_t> object can store an arbitray pointer
   that callers can use for any purpose. These two functions
   provide for accessing or setting this pointer. */

#define ddjvu_document_set_user_data(document,userdata) \
   ddjvu_job_set_user_data(ddjvu_document_job(document),userdata)
#define ddjvu_document_get_user_data(document) \
   ddjvu_job_get_user_data(ddjvu_document_job(document))

/* ddjvu_document_decoding_status ---
   ddjvu_document_decoding_done, ddjvu_document_decoding_error ---
   This function returns the status of the document header decoding job */
   
#define ddjvu_document_decoding_status(document) \
   ddjvu_job_status(ddjvu_document_job(document))
#define ddjvu_document_decoding_done(document) \
   (ddjvu_document_decoding_status(document) >= DDJVU_JOB_OK)
#define ddjvu_document_decoding_error(document) \
   (ddjvu_document_decoding_status(document) >= DDJVU_JOB_FAILED)


/* ------- STREAMS ------- */


/* ddjvu_message_t::m_newstream --- 
   Newstream messages are generated whenever the decoder
   needs to access raw DjVu data.  The caller must then
   provide the requested data using <ddjvu_stream_write> 
   and <ddjvu_stream_close>. 

   In the case of indirect documents, a single decoder 
   might simultaneously request several streams of data.  
   Each stream is identified by a small integer <streamid>.

   The first <m_newstream> message always has member
   <streamid> set to zero and member <name> set to the null
   pointer.  It indicates that the decoder needs to access
   the data in the main DjVu file.  In fact, data can be
   written to stream <0> as soon as the <ddjvu_document_t>
   object is created.

   Further <m_newstream> messages are generated to access
   the auxiliary files of indirect or indexed DjVu
   documents.  Member <name> then provides the basename of
   the auxiliary file.

   Member <url> is set according to the url argument
   provided to function <ddjvu_document_create>.  The first
   newstream message always contain the url passed to
   <ddjvu_document_create>.  Subsequent newstream messages
   contain the url of the auxiliary files for indirect or
   indexed DjVu documents. */
   
struct ddjvu_message_newstream_s { /* ddjvu_message_t::m_newstream */
  ddjvu_message_any_t  any;
  int                  streamid;
  const char          *name;
  const char          *url;
}; 


/* ddjvu_stream_write ---
   Provide raw data to the DjVu decoder.
   This function should be called as soon as the data is available,
   for instance when receiving DjVu data from a network connection.
 */

DDJVUAPI void
ddjvu_stream_write(ddjvu_document_t *document,
                   int streamid,
                   const char *data,
                   unsigned long datalen );


/* ddjvu_stream_close ---
   Indicates that no more data will be provided on a
   particular stream.  Argument <stop> most likely should be
   set to <FALSE>. Setting argument <stop> to <TRUE>
   indicates that the user has interrupted the data transfer
   (for instance by pressing the stop button of a browser)
   and that the decoding threads should be stopped as 
   soon as feasible. */

DDJVUAPI void
ddjvu_stream_close(ddjvu_document_t *document,
                   int streamid,
                   int stop );



/* ------- QUERIES ------- */


/* ddjvu_message_t::m_docinfo ---
   The <m_docinfo> message indicates that basic information
   about the document has been obtained and decoded.
   Not much can be done before this happens.
   Call <ddjvu_document_decoding_status> to determine
   whether the operation was successful. */

struct ddjvu_message_docinfo_s {
  ddjvu_message_any_t  any;
};


/* ddjvu_document_get_type ---
   Returns the type of a DjVu document.
   This function might return <DDJVU_DOCTYPE_UNKNOWN>
   when called before receiving a <m_docinfo> message. */

typedef enum {
  DDJVU_DOCTYPE_UNKNOWN=0,
  DDJVU_DOCTYPE_SINGLEPAGE,
  DDJVU_DOCTYPE_BUNDLED, 
  DDJVU_DOCTYPE_INDIRECT,
  DDJVU_DOCTYPE_OLD_BUNDLED, /* obsolete */
  DDJVU_DOCTYPE_OLD_INDEXED, /* obsolete */
} ddjvu_document_type_t;

DDJVUAPI ddjvu_document_type_t
ddjvu_document_get_type(ddjvu_document_t *document);


/* ddjvu_document_get_pagenum ---
   Returns the number of pages in a DjVu document.
   This function might return 1 when called 
   before receiving a <m_docinfo> message */
   
DDJVUAPI int
ddjvu_document_get_pagenum(ddjvu_document_t *document);



/* ------- ADVANCED ------- */


/* ddjvu_document_get_filenum --
   Returns the number of component files.
   This function might return 0 when called
   before receiving a <m_docinfo> message */
   
DDJVUAPI int
ddjvu_document_get_filenum(ddjvu_document_t *document);


/* ddjvu_document_get_fileinfo --
   Returns information about component file <fileno>.
   This function might return <DDJVU_JOB_STARTED> when
   called before receiving a <m_docinfo> message.
   String pointers in the returned data structure 
   might be null. Strings are UTF8 encoded and remain 
   allocated as long as the ddjvu_document_t object exists.

   Changes for ddjvuapi=18
   - Redefined as a macro passing the structure size.
*/

typedef struct ddjvu_fileinfo_s {
  char  type;                   /* [P]age, [T]humbnails, [I]nclude. */
  int   pageno;                 /* Negative when not applicable. */
  int   size;                   /* Negative when unknown. */
  const char *id;               /* File identifier. */
  const char *name;             /* Name for indirect documents. */
  const char *title;            /* Page title. */
} ddjvu_fileinfo_t;

#define ddjvu_document_get_fileinfo(d,f,i) \
   ddjvu_document_get_fileinfo_imp(d,f,i,sizeof(ddjvu_fileinfo_t))

DDJVUAPI ddjvu_status_t
ddjvu_document_get_fileinfo_imp(ddjvu_document_t *document, int fileno, 
                                ddjvu_fileinfo_t *info, unsigned int infosz);


/* ddjvu_document_search_pageno --- DEPRECATED. */

DDJVUAPI int ddjvu_document_search_pageno(ddjvu_document_t*, const char*);


/* ddjvu_document_check_pagedata ---
   Returns a non zero result if the data for page <pageno>
   is already in memory. When this is the case, functions 
   <ddjvu_document_get_pageinfo> and <ddjvu_document_get_pagetext> 
   return the information immediately.
   This function causes the emission of <m_pageinfo> messages 
   with zero in the <m_any.page> field whenever a new file
   is completely downloaded. */

DDJVUAPI int 
ddjvu_document_check_pagedata(ddjvu_document_t *document, int pageno);


/* ddjvu_document_get_pageinfo ---
   Attempts to obtain information about page <pageno>
   without decoding the page. If the information is available,
   the function returns <DDJVU_JOB_OK> and fills the <info> structure. 
   Otherwise it starts fetching page data and returns <DDJVU_JOB_STARTED>. 
   This function causes the emission of <m_pageinfo> messages 
   with zero in the <m_any.page> field.
   Typical synchronous usage:

   ddjvu_status_t r;
   ddjvu_pageinfo_t info;
   while ((r=ddjvu_document_get_pageinfo(doc,pageno,&info))<DDJVU_JOB_OK)
     handle_ddjvu_messages(ctx, TRUE);
   if (r>=DDJVU_JOB_FAILED)
     signal_error();

   Changes for ddjvuapi=18
   - Redefined as a macro passing the structure size.
   - Added fields 'rotation' and 'version'.
*/      

typedef struct ddjvu_pageinfo_s {
  int width;                    /* page width (in pixels) */
  int height;                   /* page height (in pixels) */
  int dpi;                      /* page resolution (in dots per inche) */
  int rotation;                 /* initial page orientation */
  int version;                  /* page version */
} ddjvu_pageinfo_t;

#define ddjvu_document_get_pageinfo(d,p,i) \
   ddjvu_document_get_pageinfo_imp(d,p,i,sizeof(ddjvu_pageinfo_t))

DDJVUAPI ddjvu_status_t
ddjvu_document_get_pageinfo_imp(ddjvu_document_t *document, int pageno, 
                                ddjvu_pageinfo_t *info, unsigned int infosz );




/* ddjvu_document_get_pagedump --
   This function returns a UTF8 encoded text describing the contents 
   of page <pageno> using the same format as command <djvudump>. 
   The returned string must be deallocated using <free()>.
   It returns <0> when the information is not yet available. 
   It may then cause then the emission of <m_pageinfo> 
   messages with null <m_any.page>.
*/   

DDJVUAPI char *
ddjvu_document_get_pagedump(ddjvu_document_t *document, int pageno);


/* ddjvu_document_get_filedump --
   This function returns a UTF8 encoded text describing the contents 
   of file <fileno> using the same format as command <djvudump>. 
   The returned string must be deallocated using <free()>.
   It returns <0> when the information is not yet available. 
   It may then cause then the emission of <m_pageinfo> 
   messages with null <m_any.page>.
*/   

DDJVUAPI char *
ddjvu_document_get_filedump(ddjvu_document_t *document, int fileno);




/* -------------------------------------------------- */
/* DJVU_PAGE_T                                        */
/* -------------------------------------------------- */


/* ddjvu_page_create_by_pageno ---
   Each page of a document can be accessed by creating a
   <ddjvu_page_t> object with this function.  Argument
   <pageno> indicates the page number, starting with page
   <0> to <pagenum-1>. This function may return NULL
   when called before receiving the <m_docinfo> message.
   Calling this function also initiates the data transfer 
   and the decoding threads for the specified page.  
   Various messages will document the progress of these 
   operations. Error messages will be generated if 
   the page does not exists. */

DDJVUAPI ddjvu_page_t *
ddjvu_page_create_by_pageno(ddjvu_document_t *document,
                            int pageno);

/* ddjvu_page_create_by_pageid ---
   This function is similar to <ddjvu_page_create_by_pageno>
   but identifies the desired page by name instead of page
   number. */

DDJVUAPI ddjvu_page_t *
ddjvu_page_create_by_pageid(ddjvu_document_t *document,
                            const char *pageid);


/* ddjvu_page_job ---
   Access the job object in charge of decoding the document header. 
   In fact <ddjvu_page_t> is a subclass of <ddjvu_job_t>
   and this function is a type cast. */

DDJVUAPI ddjvu_job_t *
ddjvu_page_job(ddjvu_page_t *page);


/* ddjvu_page_release ---
   Release a reference to a <ddjvu_page_t> object.
   The calling program should no longer reference this object.
   The object itself will be destroyed as soon as no other object
   or thread needs it. */

#define ddjvu_page_release(page) \
  ddjvu_job_release(ddjvu_page_job(page))


/* ddjvu_page_set_user_data ---
   ddjvu_page_get_user_data ---
   Each <ddjvu_paqge_t> object can store an arbitray pointer
   that callers can use for any purpose. These two functions
   provide for accessing or setting this pointer. */

#define ddjvu_page_set_user_data(page,userdata) \
   ddjvu_job_set_user_data(ddjvu_page_job(page),userdata)
#define ddjvu_page_get_user_data(page) \
   ddjvu_job_get_user_data(ddjvu_page_job(page))

/* ddjvu_page_decoding_status ---
   ddjvu_page_decoding_done ---
   ddjvu_page_decoding_error ---
   These calls return the status of the page decoding job. */
   
#define ddjvu_page_decoding_status(page) \
   ddjvu_job_status(ddjvu_page_job(page))
#define ddjvu_page_decoding_done(page) \
    (ddjvu_page_decoding_status(page) >= DDJVU_JOB_OK)
#define ddjvu_page_decoding_error(page) \
    (ddjvu_page_decoding_status(page) >= DDJVU_JOB_FAILED)


/* ------- MESSAGES ------- */


/* ddjvu_message_t::m_pageinfo ---
   The page decoding process generates this message
   - when basic page information is available and 
     before any <m_relayout> or <m_redisplay> message,
   - when the page decoding thread terminates.
   You can distinguish both cases using 
   function ddjvu_page_decoding_status().
   Messages <m_pageinfo> are also generated as a consequence of 
   functions such as <ddjvu_document_get_pageinfo>. 
   The field <m_any.page> of such message is null.
*/

struct ddjvu_message_pageinfo_s {  /* ddjvu_message_t::m_pageinfo */
  ddjvu_message_any_t  any;
}; 


/* ddjvu_message_t::m_relayout ---
   This message is generated when a DjVu viewer
   should recompute the layout of the page viewer
   because the page size and resolution information has
   been updated. */

struct ddjvu_message_relayout_s {  /* ddjvu_message_t::m_relayout */
  ddjvu_message_any_t  any;
}; 


/* ddjvu_message_t::m_redisplay ---
   This message is generated when a DjVu viewer
   should call <ddjvu_page_render> and redisplay
   the page. This happens, for instance, when newly 
   decoded DjVu data provides a better image. */

struct ddjvu_message_redisplay_s { /* ddjvu_message_t::m_redisplay */
  ddjvu_message_any_t  any;
}; 


/* ddjvu_message_t::m_chunk ---
   This message indicates that an additional chunk
   of DjVu data has been decoded.  Member <chunkid>
   indicates the type of the DjVu chunk. */

struct ddjvu_message_chunk_s {     /* ddjvu_message_t::m_chunk */
  ddjvu_message_any_t  any;
  const char *chunkid;
}; 

/* About page messages --
   Both the <m_relayout> and <m_redisplay> messages are derived from the
   <m_chunk> message.  They are intended for driving a djvu image viewer. 
   When receiving <m_relayout>, the viewer should get the image size, decide
   zoom factors, and place the image area, scrollbars, toolbars, and other gui
   objects.  When receiving <m_redisplay>, the viewer should invalidate the
   image area so that the gui toolkit calls the repaint event handler. This
   handler should call ddjvu_page_render() and paint the part of the
   image that needs repainting. */



/* ------- QUERIES ------- */

/* ddjvu_page_get_width ---
   Returns the page width in pixels. Calling this function 
   before receiving a <m_pageinfo> message always yields <0>. */

DDJVUAPI int
ddjvu_page_get_width(ddjvu_page_t *page);


/* ddjvu_page_get_height---
   Returns the page height in pixels. Calling this function 
   before receiving a <m_pageinfo> message always yields <0>. */

DDJVUAPI int
ddjvu_page_get_height(ddjvu_page_t *page);

/* ddjvu_page_get_resolution ---
   Returns the page resolution in pixels per inch  (dpi).
   Calling this function before receiving a <m_pageinfo>
   message yields a meaningless but plausible value. */

DDJVUAPI int
ddjvu_page_get_resolution(ddjvu_page_t *page);


/* ddjvu_page_get_gamma ---
   Returns the gamma of the display for which this page was designed.
   Calling this function before receiving a <m_pageinfo>
   message yields a meaningless but plausible value. */

DDJVUAPI double
ddjvu_page_get_gamma(ddjvu_page_t *page);


/* ddjvu_page_get_version ---
   Returns the version of the djvu file format.
   Calling this function before receiving a <m_pageinfo>
   message yields a meaningless but plausible value. */

DDJVUAPI int
ddjvu_page_get_version(ddjvu_page_t *page);

/* ddjvu_code_get_version ---
   Returns the version of the djvu file format
   implemented by this library. More or less graceful 
   degradation might arise if this is smaller than
   the number returned by <ddjvu_page_get_version>. */

DDJVUAPI int
ddjvu_code_get_version(void);


/* ddjvu_page_get_type ---
   Returns the type of the page data.
   Calling this function before the termination of the
   decoding process might returns <DDJVU_PAGETYPE_UNKNOWN>. */

typedef enum {
  DDJVU_PAGETYPE_UNKNOWN,
  DDJVU_PAGETYPE_BITONAL,
  DDJVU_PAGETYPE_PHOTO,
  DDJVU_PAGETYPE_COMPOUND,
} ddjvu_page_type_t;

DDJVUAPI ddjvu_page_type_t
ddjvu_page_get_type(ddjvu_page_t *page);


/* ddjvu_page_get_{short,long}_description --- DEPRECATED */

DDJVUAPI char *ddjvu_page_get_short_description(ddjvu_page_t *);
DDJVUAPI char *ddjvu_page_get_long_description(ddjvu_page_t *);


/* ddjvu_page_set_rotation ---
   Changes the counter-clockwise rotation angle for a DjVu page.
   Calling this function before receiving a <m_pageinfo>
   message has no good effect. */

typedef enum {
  DDJVU_ROTATE_0   = 0,
  DDJVU_ROTATE_90  = 1,
  DDJVU_ROTATE_180 = 2,
  DDJVU_ROTATE_270 = 3,
} ddjvu_page_rotation_t;

DDJVUAPI void
ddjvu_page_set_rotation(ddjvu_page_t *page,
                        ddjvu_page_rotation_t rot);


/* ddjvu_page_get_rotation ---
   Returns the counter-clockwise rotation angle for the DjVu page.
   The rotation is automatically taken into account
   by <ddjvu_page_render>, <ddjvu_page_get_width>
   and <ddjvu_page_get_height>. */

DDJVUAPI ddjvu_page_rotation_t
ddjvu_page_get_rotation(ddjvu_page_t *page);


/* ddjvu_page_get_initial_rotation ---
   Returns the page rotation specified by the 
   orientation flags in the DjVu file. 
   [brain damage warning] This is useful because
   maparea coordinates in the annotation chunks
   are expressed relative to the rotated coordinates
   whereas text coordinates in the hidden text data
   are expressed relative to the unrotated coordinates. */

DDJVUAPI ddjvu_page_rotation_t
ddjvu_page_get_initial_rotation(ddjvu_page_t *page);



/* ------- RENDER ------- */


/* ddjvu_render_mode_t ---
   Various ways to render a page. */

typedef enum {
  DDJVU_RENDER_COLOR = 0,       /* color page or stencil */
  DDJVU_RENDER_BLACK,           /* stencil or color page */
  DDJVU_RENDER_COLORONLY,       /* color page or fail */
  DDJVU_RENDER_MASKONLY,        /* stencil or fail */
  DDJVU_RENDER_BACKGROUND,      /* color background layer */
  DDJVU_RENDER_FOREGROUND,      /* color foreground layer */
} ddjvu_render_mode_t;


/* ddjvu_rect_t ---
   This structure specifies the location of a rectangle.
   Coordinates are usually expressed in pixels relative to 
   the BOTTOM LEFT CORNER (but see ddjvu_format_set_y_direction).
   Members <x> and <y> indicate the position of the bottom left 
   corner of the rectangle Members <w> and <h> indicate the 
   width and height of the rectangle. */

struct ddjvu_rect_s {
  int x, y;
  unsigned int w, h;
};


/* ddjvu_page_render --
   Renders a segment of a page with arbitrary scale.
   Argument <mode> indicates what image layers 
   should be rendered. 

   Conceptually this function renders the full page
   into a rectangle <pagerect> and copies the
   pixels specified by rectangle <renderrect>
   into the buffer starting at position <imagebuffer>.
   The actual code is much more efficient than that.

   The final image is written into buffer <imagebuffer>.  
   Argument <pixelformat> specifies the expected pixel format.  
   Argument <rowsize> specifies the number of BYTES from 
   one row to the next in the buffer. The buffer must be 
   large enough to accomodate the desired image.

   This function makes a best effort to compute an image
   that reflects the most recently decoded data.  It might
   return <FALSE> to indicate that no image could be
   computed at this point, and that nothing was written into
   the buffer. */

DDJVUAPI int
ddjvu_page_render(ddjvu_page_t *page,
                  const ddjvu_render_mode_t mode,
                  const ddjvu_rect_t *pagerect,
                  const ddjvu_rect_t *renderrect,
                  const ddjvu_format_t *pixelformat,
                  unsigned long rowsize,
                  char *imagebuffer );




/* -------------------------------------------------- */
/* COORDINATE TRANSFORMS                              */
/* -------------------------------------------------- */

/* ddjvu_rectmapper_create --
   Creates a <ddjvu_rectmapper_t> data structure 
   representing an affine coordinate transformation that
   maps points from rectangle <input> to rectangle <output>.
   The transformation maintains the positions relative 
   to the coordinates of the rectangle corners. */

DDJVUAPI ddjvu_rectmapper_t *
ddjvu_rectmapper_create(ddjvu_rect_t *input, ddjvu_rect_t *output);


/* ddjvu_rectmapper_modify ---
   Modifies the coordinate transform <mapper> by redefining
   which corners of the output rectangle match those of the 
   input rectangle. This function first applies a counter-clockwise 
   rotation of <rotation> quarter-turns, and then reverses the X 
   (resp. Y) coordinates when <mirrorx> (resp. <mirrory>) is non zero. */

DDJVUAPI void
ddjvu_rectmapper_modify(ddjvu_rectmapper_t *mapper,
                        int rotation, int mirrorx, int mirrory);


/* ddjvu_rectmapper_release ---
   Destroys the <ddjvu_rect_mapper_t> structure
   returned by <ddjvu_rect_mapper_create>. */

DDJVUAPI void 
ddjvu_rectmapper_release(ddjvu_rectmapper_t *mapper);

/* ddjvu_map_point, ddjvu_map_rect ---
   Applies the coordinate transform 
   to a point or a rectangle */

DDJVUAPI void 
ddjvu_map_point(ddjvu_rectmapper_t *mapper, int *x, int *y);

DDJVUAPI void 
ddjvu_map_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect);


/* ddjvu_unmap_point, ddjvu_unmap_rect ---
   Applies the inverse coordinate transform 
   to a point or a rectangle */

DDJVUAPI void 
ddjvu_unmap_point(ddjvu_rectmapper_t *mapper, int *x, int *y);

DDJVUAPI void 
ddjvu_unmap_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect);




/* -------------------------------------------------- */
/* DJVU_FORMAT_T                                      */
/* -------------------------------------------------- */


/* ddjvu_format_style_t ---
   Enumerated type for pixel formats. */

typedef enum {
  DDJVU_FORMAT_BGR24,           /* truecolor 24 bits in BGR order */
  DDJVU_FORMAT_RGB24,           /* truecolor 24 bits in RGB order */
  DDJVU_FORMAT_RGBMASK16,       /* truecolor 16 bits with masks */
  DDJVU_FORMAT_RGBMASK32,       /* truecolor 32 bits with masks */
  DDJVU_FORMAT_GREY8,           /* greylevel 8 bits */
  DDJVU_FORMAT_PALETTE8,        /* paletized 8 bits (6x6x6 color cube) */
  DDJVU_FORMAT_MSBTOLSB,        /* packed bits, msb on the left */
  DDJVU_FORMAT_LSBTOMSB,        /* packed bits, lsb on the left */
} ddjvu_format_style_t;
   

/* ddjvu_format_create ---
   Creates a <ddjvu_format_t> object describing a pixel format.
   Argument <style> describes the generic pixel format.
   Argument <args> is an array of <nargs> unsigned ints
   providing additionnal information:
   - When style is <RGBMASK*>, argument <nargs> must be <3> or <4>.
     The three first entries of array <args> are three contiguous 
     bit masks for the red, green, and blue components of each pixel.
     The resulting color is then xored with the optional fourth entry.
   - When style is <PALETTE*>, argument <nargs> must be <216>
     and array <args> contains the 6*6*6 entries of a web
     color cube.
   - Otherwise <nargs> must be <0>. */

DDJVUAPI ddjvu_format_t *
ddjvu_format_create(ddjvu_format_style_t style, 
                    int nargs, unsigned int *args);


/* ddjvu_format_set_row_order ---
   Sets a flag indicating whether the rows in the pixel buffer
   are stored starting from the top or the bottom of the image.
   Default ordering starts from the bottom of the image.
   This is the opposite of the X11 convention. */

DDJVUAPI void
ddjvu_format_set_row_order(ddjvu_format_t *format, int top_to_bottom);


/* ddjvu_format_set_y_direction ---
   Sets a flag indicating whether the y coordinates in the drawing 
   area are oriented from bottom to top, or from top to botttom.  
   The default is bottom to top, similar to PostScript.
   This is the opposite of the X11 convention. */

DDJVUAPI void
ddjvu_format_set_y_direction(ddjvu_format_t *format, int top_to_bottom);


/* ddjvu_format_set_ditherbits ---
   Specifies the final depth of the image on the screen.
   This is used to decide which dithering algorithm should be used.
   The default is usually appropriate. */

DDJVUAPI void
ddjvu_format_set_ditherbits(ddjvu_format_t *format, int bits);


/* ddjvu_format_set_gamma ---
   Sets the gamma of the display for which the pixels are
   intended.  This will be combined with the gamma stored in
   DjVu documents in order to compute a suitable color
   correction.  The default value is 2.2. */

DDJVUAPI void
ddjvu_format_set_gamma(ddjvu_format_t *format, double gamma);


/* ddjvu_format_set_white ---
   Sets the whitepoint of the display for which the pixels are
   intended.  This will be combined with the gamma stored in
   DjVu documents in order to compute a suitable color
   correction.  The default value is 0xff,0xff,0xff. */

DDJVUAPI void
ddjvu_format_set_white(ddjvu_format_t *format, 
                       unsigned char b, unsigned char g, unsigned char r);

/* ddjvu_format_release ---
   Release a reference to a <ddjvu_format_t> object.
   The calling program should no longer reference this object. */

DDJVUAPI void
ddjvu_format_release(ddjvu_format_t *format);




/* -------------------------------------------------- */
/* THUMBNAILS                                         */
/* -------------------------------------------------- */


/* ddjvu_thumbnail_status ---
   Determine whether a thumbnail is available for page <pagenum>.
   Calling this function with non zero argument <start> initiates
   a thumbnail calculation job. Regardless of its success,
   the completion of the job is signalled by a subsequent 
   <m_thumbnail> message. */

DDJVUAPI ddjvu_status_t
ddjvu_thumbnail_status(ddjvu_document_t *document, int pagenum, int start);


/* ddjvu_message_t::m_thumbnail ---
   This message is sent when additional thumbnails are available. */

struct ddjvu_message_thumbnail_s { /* ddjvu_message_t::m_thumbnail */
  ddjvu_message_any_t  any;
  int pagenum;
}; 


/* ddjvu_thumbnail_render ---
   Renders a thumbnail for page <pagenum>.
   Argument <imagebuffer> must be large enough to contain
   an image of size <*wptr> by <*hptr> using pixel format
   <pixelformat>. Argument <rowsize> specifies the number 
   of BYTES from one row to the next in the buffer.
   This function returns <FALSE> when no thumbnail is available.
   Otherwise it returns <TRUE>, adjusts <*wptr> and <*hptr> to 
   reflect the thumbnail size, and, if the pointer <imagebuffer>
   is non zero, writes the pixel data into the image buffer. */

DDJVUAPI int
ddjvu_thumbnail_render(ddjvu_document_t *document, int pagenum, 
                       int *wptr, int *hptr,
                       const ddjvu_format_t *pixelformat,
                       unsigned long rowsize,
                       char *imagebuffer);



/* -------------------------------------------------- */
/* SAVE AND PRINT JOBS                                */
/* -------------------------------------------------- */


/* ddjvu_message_t::m_progress ---
   These messages are generated to indicate progress 
   towards the completion of a print or save job. */

struct ddjvu_message_progress_s {
  ddjvu_message_any_t any;
  ddjvu_status_t status;
  int percent;
};

/* ddjvu_document_print ---
   Converts specified pages of a djvu document into postscript.  
   This function works asynchronously in a separate thread.
   You can use the following idiom for synchronous operation:

     ddjvu_job_t *job = ddjvu_document_print(....);
     while (! ddjvu_job_done(job) )
       handle_ddjvu_messages(context, TRUE);
       
   The postscript data is written to stdio file <output>.
   Arguments <optc> and <optv> specify printing options.
   All options described on the <djvups> man page are 
   recognized, except <"-help"> and <"-verbose">.
*/

DDJVUAPI ddjvu_job_t *
ddjvu_document_print(ddjvu_document_t *document, FILE *output,
                     int optc, const char * const * optv);


/* ddjvu_document_save ---
   Saves the djvu document as a bundled djvu file.
   This function works asynchronously in a separate thread.
   You can use the following idiom for synchronous operation:

     ddjvu_job_t *job = ddjvu_document_save(....);
     while (! ddjvu_job_done(job) )
       handle_ddjvu_messages(context, TRUE);
     
   The bundled djvu data is written to file <output>
   which must be seekable. Arguments <optc> and <optv>
   can be used to pass the following options:
   * Option "-pages=<pagespec>" specify a subset of pages
     using the same syntax as program <ddjvu>.
     Reordering or duplicating pages is prohibited. 
   * Option "-indirect=<filename>" causes the creation
     of an indirect document with index file <filename>
     and auxiliary files in the same directory.
     The file name is UTF-8 encoded.
     When this option is specified, the argument <output>
     is ignored and should be NULL.
*/
DDJVUAPI ddjvu_job_t *
ddjvu_document_save(ddjvu_document_t *document, FILE *output, 
                    int optc, const char * const * optv);




/* -------------------------------------------------- */
/* S-EXPRESSIONS                                      */
/* -------------------------------------------------- */


/* DjVu files can contain ancillary information such as
   document outline, hidden text, hyperlinks, and metadata.
   Program <djvused> provides for manipulating such
   information.  Like <djvused>, the DDJVU API represents
   this information using a lisp s-expressions.  See file
   <"libdjvu/miniexp.h"> for the s-expression documentation
   and manipulation functions.  See the <djvused> man page
   for the specification of the s-expressions representing
   outlines, hidden text and annotations. It often help 
   to print s-expressions using function <miniexp_pprint>.

   WARNING: All strings in s-expression are UTF-8 encoded.  
   Strings returned by miniexp_to_str might have to be 
   converted to the locale encoding. */


/* miniexp_t --
   Opaque type representing s-expressions.
   The same definition also appears in 
   file <"libdjvu/miniexp.h">. */

#ifndef MINIEXP_H
typedef struct miniexp_s* miniexp_t;
#endif

/* ddjvu_miniexp_release -- 
   This function controls the allocation of the
   s-expressions returned by functions from the DDJVU
   API. It indicates that the s-expression <expr> is no
   longer needed and can be deallocated as soon as
   necessary. Otherwise the s-expression remains allocated
   as long as the document object exists. */

DDJVUAPI void
ddjvu_miniexp_release(ddjvu_document_t *document, miniexp_t expr);


/* ddjvu_document_get_outline -- 
   This function tries to obtain the document outline.  
   If this information is available, it returns a
   s-expression with the same syntax as function
   <print-outline> of program <djvused>.  
   Otherwise it returns <miniexp_dummy> until 
   the document header gets fully decoded.
   Typical synchronous usage:

    miniexp_t r;
    while ((r=ddjvu_document_get_outline(doc))==miniexp_dummy)
      handle_ddjvu_messages(ctx, TRUE); 

   This function returns the empty list <miniexp_nil> when
   the document contains no outline information. It can also
   return symbols <failed> or <stopped> when an error occurs
   while accessing the desired information. */

DDJVUAPI miniexp_t
ddjvu_document_get_outline(ddjvu_document_t *document);


/* ddjvu_document_get_anno --
   This function returns the document-wide annotations.
   This corresponds to a proposed change in the djvu format.
   When no new-style document-wide annotations are available
   and <compat> is true, this function searches a shared 
   annotation chunk and returns its contents.

   This function returns <miniexp_dummy> if the information
   is not yet available. It may then cause the emission 
   of <m_pageinfo> messages with null <m_any.page>.

   This function returns the empty list <miniexp_nil> when
   the document does not contain page annotations. It can also
   return symbols <failed> or <stopped> when an error occurs
   while accessing the desired information. */

DDJVUAPI miniexp_t
ddjvu_document_get_anno(ddjvu_document_t *document, int compat);


/* ddjvu_document_get_pagetext -- 
   This function tries to obtain the text information for
   page <pageno>. If this information is available, it
   returns a s-expression with the same syntax as function
   <print-txt> of program <djvused>.  Otherwise it starts
   fetching the page data and returns <miniexp_dummy>.
   This function causes the emission of <m_pageinfo> messages 
   with zero in the <m_any.page> field.
   Typical synchronous usage:

    miniexp_t r;
    while ((r=ddjvu_document_get_pagetext(doc,pageno,0))==miniexp_dummy)
      handle_ddjvu_messages(ctx, TRUE); 

   This function returns the empty list <miniexp_nil> when
   the page contains no text information. It can also return
   symbols <failed> or <stopped> when an error occurs while
   accessing the desired information. 

   Argument <maxdetail> controls the level of detail in the
   returned s-expression. Values "page", "column", "region", "para", 
   "line", and "word" restrict the output to the specified granularity.
   All other values produce a s-expression that represents
   the hidden text data as finely as possible. */

DDJVUAPI miniexp_t
ddjvu_document_get_pagetext(ddjvu_document_t *document, int pageno, 
                            const char *maxdetail);


/* ddjvu_document_get_pageanno -- 
   This function tries to obtain the annotations for
   page <pageno>. If this information is available, it
   returns a s-expression with the same syntax as function
   <print-ant> of program <djvused>.  Otherwise it starts
   fetching the page data and returns <miniexp_dummy>.
   This function causes the emission of <m_pageinfo> messages 
   with zero in the <m_any.page> field.
   Typical synchronous usage:

     miniexp_t r;
     while ((r = ddjvu_document_get_pageanno(doc,pageno))==miniexp_dummy)
       handle_ddjvu_messages(ctx, TRUE); 

   This function returns the empty list <miniexp_nil> when
   the page contains no annotations. It can also return
   symbols <failed> or <stopped> when an error occurs while
   accessing the desired information. */

DDJVUAPI miniexp_t
ddjvu_document_get_pageanno(ddjvu_document_t *document, int pageno);


/* --- Helper functions to parse annotations --- */

/* ddjvu_anno_get_bgcolor --
   Parse the annotations and extracts the desired 
   background color as a color string ("#FFFFFF"). 
   See <(background ...)> in the djvused man page.
   Returns zero if this information is not specified. */

DDJVUAPI const char *
ddjvu_anno_get_bgcolor(miniexp_t annotations);


/* ddjvu_anno_get_zoom --
   Parse the annotations and extracts the desired zoom factor.
   See <(zoom ...)> in the djvused man page.
   Returns zero if this information is not specified. */

DDJVUAPI const char *
ddjvu_anno_get_zoom(miniexp_t annotations);


/* ddjvu_anno_get_mode --
   Parse the annotations and extracts the desired display mode.
   See <(mode ...)> in the djvused man page.
   Returns zero if this information is not specified. */

DDJVUAPI const char *
ddjvu_anno_get_mode(miniexp_t annotations);


/* ddjvu_anno_get_horizalign --
   Parse the annotations and extracts how the page
   image should be aligned horizontally.
   See <(align ...)> in the djvused man page.
   Returns zero if this information is not specified. */

DDJVUAPI const char *
ddjvu_anno_get_horizalign(miniexp_t annotations);


/* ddjvu_anno_get_vertalign --
   Parse the annotations and extracts how the page
   image should be aligned vertically.
   See <(align ...)> in the djvused man page.
   Returns zero if this information is not specified. */

DDJVUAPI const char *
ddjvu_anno_get_vertalign(miniexp_t annotations);


/* ddjvu_anno_get_hyperlinks --
   Parse the annotations and returns a zero terminated 
   array of <(maparea ...)> s-expressions.
   The caller should free this array with function <free>.
   These s-expressions remain allocated as long
   as the annotations remain allocated.
   See also <(maparea ...)> in the djvused man page. */

DDJVUAPI miniexp_t *
ddjvu_anno_get_hyperlinks(miniexp_t annotations);


/* ddjvu_anno_get_metadata_keys --
   Parse the annotations and returns a zero terminated 
   array of key symbols for the page metadata.
   The caller should free this array with function <free>.
   See also <(metadata ...)> in the djvused man page. */

DDJVUAPI miniexp_t *
ddjvu_anno_get_metadata_keys(miniexp_t annotations);


/* ddjvu_anno_get_metadata --
   Parse the annotations and returns the metadata string
   corresponding to the metadata key symbol <key>.
   The string remains allocated as long as the 
   annotations s-expression remain allocated.
   Returns zero if no such key is present. */

DDJVUAPI const char *
ddjvu_anno_get_metadata(miniexp_t annotations, miniexp_t key);


/* ddjvu_anno_get_xmp --
   Parse the annotations and returns the xmp metadata string.
   The string remains allocated as long as the 
   annotations s-expression remain allocated.
   Returns zero if no such key is present. */

DDJVUAPI const char *
ddjvu_anno_get_xmp(miniexp_t annotations);


/* -------------------------------------------------- */
/* DJVU_MESSAGE_T                                     */
/* -------------------------------------------------- */


/* We can now define the djvu_message_t union */

union ddjvu_message_s {
  struct ddjvu_message_any_s        m_any;
  struct ddjvu_message_error_s      m_error;
  struct ddjvu_message_info_s       m_info;
  struct ddjvu_message_newstream_s  m_newstream;
  struct ddjvu_message_docinfo_s    m_docinfo;
  struct ddjvu_message_pageinfo_s   m_pageinfo;
  struct ddjvu_message_chunk_s      m_chunk;
  struct ddjvu_message_relayout_s   m_relayout;
  struct ddjvu_message_redisplay_s  m_redisplay;
  struct ddjvu_message_thumbnail_s  m_thumbnail;
  struct ddjvu_message_progress_s   m_progress;
};


/* -------------------------------------------------- */
/* BACKDOORS                                          */
/* -------------------------------------------------- */

#ifdef __cplusplus
} // extern "C"
#endif

/* ddjvu_get_DjVuImage ---
   ddjvu_get_DjVuDocument ---
   These functions provide an access to the libdjvu objects 
   associated with the ddjvuapi objects.  These backdoors can
   be useful for advanced manipulations.  These two functions 
   are declared in C++ when file <"ddjvuapi.h"> is included 
   after the libdjvu header files <"DjVuImage.h"> and
   <"DjVuDocument.h">. */

#ifdef __cplusplus
# ifndef NOT_USING_DJVU_NAMESPACE
#  ifdef _DJVUIMAGE_H
DDJVUAPI GP<DjVuImage>
ddjvu_get_DjVuImage(ddjvu_page_t *page);
#  endif
#  ifdef _DJVUDOCUMENT_H
DDJVUAPI GP<DjVuDocument>
ddjvu_get_DjVuDocument(ddjvu_document_t *document);
#  endif
# endif
#endif

#endif /* DDJVUAPI_H */