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
|
===============================================================================
Developers notes for libicns 0.5.1 - March 6th, 2008
Copyright (C) 2001-2008 Mathew Eis <mathew@eisbox.net>
===============================================================================
This file is indented for those wishing to contribute to libicns
-------------------------------------------------------------------------------
To develop an application using libicns, please see the file APIDOCS
===============================================================================
1) Preprocessor constants
2) Debugging
3) Jasper vs OpenJPEG
4) Versioning Notes
5) Naming Conventions
6) Endianness issues
7) icns data format
===============================================================================
Preprocessor constants
These are generally expected to be defined by the makefile, but can
be hardcoded into icns.h if necessary
To enable debugging messages
#define ICNS_DEBUG 1
To enable libjasper support for 256x256 and 512x512 icons
#define ICNS_JASPER
To enable libopenjpeg support for 256x256 and 512x512 icons
#define ICNS_OPENJPEG
===============================================================================
Debugging
Normal error messages will be displayed by libicns even without debugging
enabled, however, enabling ICNS_DEBUG will enable an _EXTENSIVE_ amount
of detailed debugging messages that should help solve any problems within
libicns.
===============================================================================
Jasper vs OpenJPEG
Jasper and OpenJPEG are both excellent JPEG2000 decoders, however, their
presence on various linux distributions is at present uncertain.
Jasper (libjasper)
As of 1.9001 it may 'crash' unless the library is built with -DNDEBUG.
There is an assertion in the decoding library (jpc_dec.c)
that fails if there are not 3 channels or components (RGB). The
data in icns files is usually RGBA - 4 channels. Thus, the
assert will cause the program to crash. If that is fixed, it works fine.
OpenJPEG (libopenjpeg)
Building libicns against the OpenJPEG library will provide full read
support of 256x256 and 512x512 icns data. However, it's distribution at
present is quite limited, and there seems to be an ongoing debate as
to it's compatability with free software guidelines.
===============================================================================
Version information
IMPORTANT:
There are two versions in use:
1) The library interface version
2) The package release version
-------------------------------------------------------------------------------
Library interface versioning follows GNU libtool versioning to the letter
1:0:0 (CURRENT:REVISION:AGE)
See GNU libtool documentation for more information:
http://www.gnu.org/software/libtool/manual.html#Libtool-versioning
Please take the time to understand this before making changes to libicns
-------------------------------------------------------------------------------
package release versions are in the format of: 0.0.0 (MAJOR.MINOR.REVISION)
The revision number should increase with each development change, and return
to zero with any major or minor change
The minor number should increase with change that adds, removes, or changes
the functionality of libicns or it's utility programs.
The major number should increase with any change that dramatically breaks
compatability with some major part of the library or utilities
===============================================================================
Naming conventions
Where possible, the naming conventions are to be similar in manner to the
libpng library. libpng has been around for a long time, it's naming conventions
are mature, and developers are well aquanted with them.
===============================================================================
Endianness issues
-------------------------------------------------------------------------------
Everything in libicns is in native endian format, with two exceptions:
int icns_export_family_data(icns_family_t *iconFamily,icns_uint32_t *dataSizeOut,unsigned char **dataPtrOut);
Here, the outgoing data pointer will have big endian values where necessary
int icns_import_family_data(icns_uint32_t dataSize,unsigned char *data,icns_family_t **iconFamilyOut);
Here, the incoming icon family MUST be in 'native' big endian where appropriate
These two functions call icns_export_family_data and icns_import_family_data:
int icns_write_family_to_file(FILE *dataFile,icns_family_t *iconFamilyIn);
int icns_read_family_from_file(FILE *dataFile,icns_family_t **iconFamilyOut);
The resulting data written to the file is thus in big-endian format.
-------------------------------------------------------------------------------
All endian swapping is handled by icns_io by icns.c with the following:
#define ICNS_READ_UNALIGNED_BE(val, addr, type) icns_read_be(&(val), (addr), sizeof(type))
static inline void icns_read_be(void *outp, void *inp, int size)
#define ICNS_WRITE_UNALIGNED_BE(addr, val, type) icns_write_be((addr), &(val), sizeof(type))
static inline void icns_write_be(void *outp, void *inp, int size)
As the macro names imply, these functions are safe to use on architectures
that do not deal well with unaligned memory access.
-------------------------------------------------------------------------------
Where there are endian issues in the first place
The 'icns' icon family type has been in existence since the Mac 68k. The data
stored within the files is, therefore, big-endian native. From experience, it
seems unclear whether we are guaranteed this to be the case.
The current definitive documentation on the issue seems to be found in the
Apple Developer Connection document "Guidelines for Swapping Bytes" from
"Universal Binary Programming Guidelines Second Edition" - see as follows:
-------------------------------------------------------------------------------
Be aware of which functions return big-endian data, and use them appropriately.
These include the BSD Sockets networking functions, the DNSServiceDiscovery
functions (for example, TCP and UDP ports are specified in network byte order),
and the ColorSync profile functions (for which all data is big-endian). The
IconFamilyElement and IconFamilyResource data types (which also include the
data types IconFamilyPtr and IconFamilyHandle) are always big-endian. There
may be other functions and data types that are not listed here. Consult the
appropriate API reference for information on data returned by a function. For
more information see
Network-Related Data.
-------------------------------------------------------------------------------
Source: http://developer.apple.com/documentation/MacOSX/Conceptual/
universal_binary/universal_binary_byte_swap/chapter_4_section_3.html
Since Apple's own Developer Documentation indicates icns is ALWAYS big-endian
libicns assumes that all data will be in the big endian format, and therefore
assumes any data that is not big endian to be corrupt. Perhaps at some point
in the future it could add support for recovering an improperly written file.
===============================================================================
icns data format is basically an 8-byte header, followed by icns elements
---- 8 byte header ----
+4 byte type id, always 'icns'
+4 byte int - total size of icns data: equal to total icns size
---- icns_element objects ----
|---- 8 byte header ----
|+4 byte type id 'ICN#', 'icl8', etc...
|+4 byte int - total size of element data: equal to size of element
|==== raw, rle, or jp2 image data
|---- 8 byte header ----
|+4 byte type id 'ICN#', 'icl8', etc...
|+4 byte int - total size of image data: equal to size of element
|==== raw, rle, or jp2 image data
|EOF
===============================================================================
icns element is basically an 8-byte header, followed by icon data
+4 byte type id 'ICN#', 'icl8', etc...
+4 byte int - total size of icns data: equal to total element size
== data size equal to (elementSize - 8)
1-bit ich#, icm#, ics#, ICN#, icon notes
- data is 8 pixels to a byte.
- mask data follows the icon data
- example: data should be 256 bytes long for 32x32 icons
--- 128 bytes (32*32) / 8 for the icon data
--- 128 bytes (32*32) / 8 for the mask data
4-bit ich4, icm4, ics4, icl4, icon notes
- data is 2 pixels to a byte, mask data is not part of the resource
- data is in 16 indexed colors, libicns provides the 32-bit colormap
- example: data should be 512 bytes long for 32x32 icons
--- 512 bytes (32*32) / 2 for the icon data
8-bit ich8, icm8, ics8, icl8, icon notes
- data is 1 pixels to a byte, mask data is not part of the resource
- data is in 256 indexed colors, libicns provides the 32-bit colormap
- example: data should be 1024 bytes long for 32x32 icons
--- 1024 bytes (32*32) for the icon data
32-bit icon notes (size < 256x256)
- data may or may not be RLE ecoded. Older icons never were, but newer
- icon editors seem to RLE encode even 16x16 32-bit icons. Mac OS seems
- to have no problem with this although only 128x128 icons were originally
- compressed using RLE.
32-bit icon notes (size >= 256x256)
- data is jp2 encoded
==============================================================================
|
