• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# scripts/pnglibconf.dfa - library build configuration control
2#
3@/*- pnglibconf.dfn intermediate file
4@ *  generated from scripts/pnglibconf.dfa
5@ */
6#
7com pnglibconf.h - library build configuration
8com
9version
10com
11com Copyright (c) 2018-2019 Cosmin Truta
12com Copyright (c) 1998-2002,2004,2006-2018 Glenn Randers-Pehrson
13com
14com This code is released under the libpng license.
15com For conditions of distribution and use, see the disclaimer
16com and license in png.h
17com
18
19file pnglibconf.h scripts/pnglibconf.dfa PNGLCONF_H
20
21# This file is preprocessed by scripts/options.awk and the
22# C compiler to generate 'pnglibconf.h' - a list of all the
23# configuration options.  The file lists the various options
24# that can *only* be specified during the libpng build;
25# pnglibconf.h freezes the definitions selected for the specific
26# build.
27#
28# The syntax is detailed in scripts/options.awk; this is a summary
29# only:
30#
31# setting <name> [requires ...] [default]
32#    #define PNG_<name> <value>  /* value comes from current setting */
33# option <name> [requires ...] [if ...] [enables ...] [disabled]
34#    #define PNG_<name>_SUPPORTED if the requirements are met and
35#    enable the other options listed
36# chunk <name> [requires ...] [enables ...] [disabled]
37#    Enable chunk processing for the given ancillary chunk; any
38#    'requires something' expands to READ_something for read and
39#    WRITE_something for write, but the enables list members are
40#    used as given (e.g. enables GAMMA just expands to that on the
41#    correspond READ_name and WRITE_name lines.)
42#
43# "," may be used to separate options on an 'option' line and is ignored; it
44# doesn't change the meaning of the line.  (NOT setting, where "," becomes
45# part of the setting!)  A comma at the end of an option line causes a
46# continuation (the next line is included in the option too.)
47#
48# Note that the 'on' and 'off' keywords, while valid on both option
49# and chunk, should not be used in this file because they force the
50# relevant options on or off.
51
52#----------------------------------------------------------------------
53
54# The following setting, option and chunk values can all be changed
55# while building libpng:
56#
57# setting: change 'setting' lines to fine tune library performance;
58#   changes to the settings don't affect the libpng API functionally
59#
60# option: change 'option' lines to remove or add capabilities from
61#   or to the library; options change the library API
62#
63# chunk: change 'chunk' lines to remove capabilities to process
64#   optional ('ancillary') chunks.  This does not prevent PNG
65#   decoding but does change the libpng API because some chunks
66#   will be ignored.
67#
68# There are three ways of disabling features, in no particular order:
69#
70# 1) Create 'pngusr.h', enter the required private build information
71# detailed below and #define PNG_NO_<option> for each option you
72# don't want in that file in that file.  You can also turn on options
73# using PNG_<option>_SUPPORTED.  When you have finished rerun
74# configure and rebuild pnglibconf.h file with -DPNG_USER_CONFIG:
75#
76#  make clean
77#  CPPFLAGS='-DPNG_USER_CONFIG' ./configure
78#  make pnglibconf.h
79#
80# pngusr.h is only used during the creation of pnglibconf.h, but it
81# is safer to ensure that -DPNG_USER_CONFIG is specified throughout
82# the build by changing the CPPFLAGS passed to the initial ./configure
83#
84# 2) Add definitions of the settings you want to change to
85# CPPFLAGS; for example:
86#
87#   -DPNG_DEFAULT_READ_MACROS=0
88#
89# (This would change the default to *not* use read macros.)  Be
90# very careful to change only settings that don't alter the API
91# because this approach bypasses the private build checking.  You
92# can also change settings from pngpriv.h (read pngpriv.h) safely
93# without API changes.  Do that in the same way.
94#
95# 3) Write a new '.dfa' file (say 'pngusr.dfa') and in this file
96# provide override values for setting entries and turn option or
97# chunk values explicitly 'on' or 'off':
98#
99#    setting FOO default VALUE
100#    option BAR [on|off]
101#
102# Then add this file to the options.awk command line (the *first*
103# one) after this file.  The make macro DFA_XTRA is provided to make
104# this easier (set it like CPPFLAGS prior to running ./configure).
105# Look at the builds below contrib/pngminim for some extreme examples
106# of how this can be used.
107#
108# Don't edit this file unless you are contributing a patch to
109# libpng and need new or modified options/settings.
110#----------------------------------------------------------------------
111
112# The following causes commented out #undef lines to be written to
113# pnglibconf.h; this can be stopped by logunsupported=0 in a later
114# file or on the command line (after pnglibconf.dfa)
115
116logunsupported = 1
117
118# The following allows the output from configure to modify the contents of
119# pnglibconf.h
120
121@#ifdef HAVE_CONFIG_H
122@#  include "config.h"
123@#endif
124
125# PNG_USER_CONFIG has to be defined on the compiler command line
126# to cause pngusr.h to be read while constructing pnglibconf.h
127#
128# If you create a private DLL you need to define the following
129# macros in the file 'pngusr.h' and set -DPNG_USER_CONFIG for
130# compilation (i.e. in CPPFLAGS.)
131# #define PNG_USER_PRIVATEBUILD \
132#     <Describes by whom and why this version of the DLL was built>
133#  e.g. #define PNG_USER_PRIVATEBUILD "Build by MyCompany for xyz reasons."
134# #define PNG_USER_DLLFNAME_POSTFIX <two-letter postfix that serve to
135#        distinguish your DLL from those of the official release. These
136#        correspond to the trailing letters that come after the version
137#        number and must match your private DLL name>
138#  e.g. // private DLL "libpng13gx.dll"
139#       #define PNG_USER_DLLFNAME_POSTFIX "gx"
140#
141# The following macros are also at your disposal if you want to complete the
142# DLL VERSIONINFO structure.
143# - PNG_USER_VERSIONINFO_COMMENTS
144# - PNG_USER_VERSIONINFO_COMPANYNAME
145# - PNG_USER_VERSIONINFO_LEGALTRADEMARKS
146
147# It is necessary to include configures definitions here so that AC_DEFINE
148# in configure.ac works in a comprehensible way
149@#if defined(HAVE_CONFIG_H) && !defined(PNG_NO_CONFIG_H)
150@#  include "config.h"
151@#endif
152
153@#ifdef PNG_USER_CONFIG
154@#  include "pngusr.h"
155@#endif
156
157# This is a special fixup for the Watcom C compiler on Windows, which has
158# multiple procedure call standards.  Unless PNG_API_RULE is set explicitly
159# (i.e. if it is not defined at this point) it will be forced to '2' here when
160# using Watcom.  This indicates to the other header files that Watcom behaviour
161# is required where appropriate.
162
163@#ifdef __WATCOMC__
164@#  ifndef PNG_API_RULE
165@#     define PNG_API_RULE 2 /* Use Watcom calling conventions */
166@#  endif
167@#endif
168
169# IN DEVELOPMENT
170# These are currently experimental features; define them if you want (NOTE:
171# experimental options must be disabled before they are defined in this file!)
172
173# NONE
174
175# Note that PNG_USER_CONFIG only has an effect when building
176# pnglibconf.h
177
178setting USER_CONFIG
179setting USER_PRIVATEBUILD
180setting USER_DLLFNAME_POSTFIX
181setting USER_VERSIONINFO_COMMENTS
182setting USER_VERSIONINFO_COMPANYNAME
183setting USER_VERSIONINFO_LEGALTRADEMARKS
184
185# Record the 'API rule' used to select calling conventions on
186# those systems that support such things (see all the comments in
187# pngconf.h)
188# Changing this setting has a fundamental affect on the PNG ABI,
189# do not release shared libraries with this changed.
190
191setting API_RULE default 0
192
193# This allows a prefix to be added to the front of every API function name (and
194# therefore every symbol) by redefining all the function names with the prefix
195# at the end of pnglibconf.h.  It also turns on similar internal symbol renaming
196# by causing a similar build-time only file, pngprefix.h, to be generated.
197
198setting PREFIX
199
200# Implementation specific control of the optimizations, enabled by those
201# hardware or software options that need it (typically when run-time choices
202# must be made by the user)
203option SET_OPTION disabled
204
205# These options are specific to the ARM NEON hardware optimizations.  At present
206# these optimizations depend on GCC specific pre-processing of an assembler (.S)
207# file so they probably won't work with other compilers.
208#
209# ARM_NEON_OPT: unset: check at compile time (__ARM_NEON__ must be defined by
210#                      the compiler, typically as a result of specifying
211#                      CC="gcc -mfpu=neon".)
212#                   0: disable (even if the CPU has a NEON FPU.)
213#                   1: check at run time (via ARM_NEON_{API,CHECK})
214#                   2: switch on unconditionally (inadvisable - instead pass
215#                      -mfpu=neon to GCC in CC)
216#           When building libpng avoid using any setting other than '0'; '1' is
217#           set automatically when either 'API' or 'CHECK' are configured in,
218#           '2' should not be necessary as -mfpu=neon will achieve the same
219#           effect as well as applying NEON optimizations to the rest of the
220#           libpng code.
221#           NOTE: any setting other than '0' requires ALIGNED_MEMORY
222# ARM_NEON_API:   (PNG_ARM_NEON == 1) allow the optimization to be switched on
223#                 with png_set_option
224# ARM_NEON_CHECK: (PNG_ARM_NEON == 1) compile a run-time check to see if Neon
225#                 extensions are supported. This is poorly supported and
226#                 deprecated - use the png_set_option API.
227setting ARM_NEON_OPT
228option ARM_NEON_API disabled requires ALIGNED_MEMORY enables SET_OPTION,
229   sets ARM_NEON_OPT 1
230option ARM_NEON_CHECK disabled requires ALIGNED_MEMORY,
231   sets ARM_NEON_OPT 1
232
233# These options are specific to the PowerPC VSX hardware optimizations.
234#
235# POWERPC_VSX_OPT: unset: check at compile time (__PPC64__,__ALTIVEC__,__VSX__
236#                      must be defined by the compiler, typically as a result
237#                      of specifying
238#                      "-mvsx -maltivec" compiler flags)
239#                   0: disable (even if the CPU supports VSX.)
240#                   1: check at run time (via POWERPC_VSX_{API,CHECK})
241#                   2: switch on unconditionally (inadvisable - instead pass
242#                      -mvsx -maltivec to compiler options)
243#           When building libpng avoid using any setting other than '0'; '1' is
244#           set automatically when either 'API' or 'CHECK' are configured in,
245#           '2' should not be necessary as "-mvsx -maltivec" will achieve the same
246#           effect as well as applying VSX optimizations to the rest of the
247#           libpng code.
248# POWERPC_VSX_API:   (PNG_POWERPC_VSX == 1) allow the optimization to be switched on
249#                 with png_set_option
250# POWERPC_VSX_CHECK: (PNG_POWERPC_VSX == 1) compile a run-time check to see if VSX
251#                 extensions are supported. This is supported not for all OSes
252#                 (see contrib/powerpc/README)
253setting POWERPC_VSX_OPT
254option POWERPC_VSX_API disabled enables SET_OPTION,
255  sets POWERPC_VSX_OPT 1
256option POWERPC_VSX_CHECK disabled,
257  sets POWERPC_VSX_OPT 1
258
259
260# These settings configure the default compression level (0-9) and 'strategy';
261# strategy is as defined by the implementors of zlib. It describes the input
262# data and modifies the zlib parameters in an attempt to optimize the balance
263# between search and huffman encoding in the zlib algorithms.  The defaults are
264# the zlib.h defaults - the apparently recursive definition does not arise
265# because the name of the setting is prefixed by PNG_
266#
267# The TEXT values are the defaults when writing compressed text (all forms)
268
269# Include the zlib header so that the defaults below are known
270@#  include <zlib.h>
271
272# The '@' here means to substitute the value when pnglibconf.h is built
273setting Z_DEFAULT_COMPRESSION default @Z_DEFAULT_COMPRESSION
274# TODO: why aren't these Z_RLE; zlib.h says that Z_RLE, specifically, is
275# appropriate for PNG images, maybe it doesn't exist in all versions?
276setting Z_DEFAULT_STRATEGY default @Z_FILTERED
277setting Z_DEFAULT_NOFILTER_STRATEGY default @Z_DEFAULT_STRATEGY
278setting ZLIB_VERNUM default @ZLIB_VERNUM
279
280# Linkage of:
281#
282#  API:      libpng API functions
283#  CALLBACK: internal non-file-local callbacks
284#  FUNCTION: internal non-file-local functions
285#  DATA:     internal non-file-local (const) data
286setting LINKAGE_API default extern
287setting LINKAGE_CALLBACK default extern
288setting LINKAGE_FUNCTION default extern
289setting LINKAGE_DATA default extern
290
291setting TEXT_Z_DEFAULT_COMPRESSION default @Z_DEFAULT_COMPRESSION
292setting TEXT_Z_DEFAULT_STRATEGY default @Z_DEFAULT_STRATEGY
293
294# Default to using the read macros
295
296setting DEFAULT_READ_MACROS default 1
297
298# The alternative is to call functions to read PNG values, if
299# the functions are turned *off* the read macros must always
300# be enabled, so turning this off will actually force the
301# USE_READ_MACROS option on (see pngconf.h)
302
303option READ_INT_FUNCTIONS requires READ
304
305# The same for write  but these can only be switched off if no writing
306# is required at all - hence the use of a 'disabled', not a 'requires'.
307# If these are needed, they are enabled in the 'WRITE options' section
308# below.
309
310option WRITE_INT_FUNCTIONS disabled
311
312# Error controls
313#
314# WARNINGS: normally on, if off no warnings are generated
315# ERROR_TEXT: normally on, if off errors happen but there is no message
316# ERROR_NUMBERS: unimplemented feature, therefore disabled
317# BENIGN_ERRORS: support for just issuing warnings for recoverable errors
318#
319# BENIGN_READ_ERRORS:
320#     By default recoverable errors on read should just generate warnings,
321#     generally safe but PNG files that don't conform to the specification will
322#     be accepted if a meaningful result can be produced.
323#
324# BENIGN_WRITE_ERRORS:
325#     By default recoverable errors on write should just generate warnings,
326#     not generally safe because this allows the application to write invalid
327#     PNG files.  Applications should enable this themselves; it's useful
328#     because it means that a failure to write an ancillary chunk can often be
329#     ignored.
330
331option WARNINGS
332option ERROR_TEXT
333option ERROR_NUMBERS disabled
334
335option BENIGN_ERRORS
336option BENIGN_WRITE_ERRORS requires BENIGN_ERRORS disabled
337option BENIGN_READ_ERRORS requires BENIGN_ERRORS
338
339
340# Generic options - affect both read and write.
341
342option MNG_FEATURES
343
344# Arithmetic options, the first is the big switch that chooses between internal
345# floating and fixed point arithmetic implementations - it does not affect any
346# APIs.  The second two (the _POINT settings) switch off individual APIs.
347#
348# Prior to libpng 1.6.8 one of the API (_POINT) variants had to be selected.  At
349# 1.6.8 this restriction has been removed; the simplified API can be used
350# without enabling any of the low level fixed/floating APIs.
351
352option FLOATING_ARITHMETIC
353option FLOATING_POINT
354option FIXED_POINT
355
356# This protects us against compilers that run on a windowing system
357# and thus don't have or would rather us not use the stdio types:
358# stdin, stdout, and stderr.  The only one currently used is stderr
359# in png_error() and png_warning().  #defining PNG_NO_CONSOLE_IO will
360# prevent these from being compiled and used. #defining PNG_NO_STDIO
361# will also prevent these, plus will prevent the entire set of stdio
362# macros and functions (FILE *, printf, etc.) from being compiled and used,
363# unless (PNG_DEBUG > 0) has been #defined.
364
365option STDIO
366option CONSOLE_IO requires STDIO
367
368# Note: prior to 1.5.0 this option could not be disabled if STDIO
369# was enabled.  Prior to 1.5.3 this option required STDIO
370
371option TIME_RFC1123
372
373# PNG_SETJMP_NOT_SUPPORTED is an old equivalent for NO_SETJMP
374
375option SETJMP
376= NO_SETJMP SETJMP_NOT_SUPPORTED
377
378# If this is disabled it is not possible for apps to get the
379# values from the 'info' structure, this effectively removes
380# quite a lot of the READ API.
381
382option EASY_ACCESS
383
384# Added at libpng-1.2.0
385
386option USER_MEM
387
388# Added at libpng-1.4.0
389
390option IO_STATE
391
392# Libpng limits: limit the size of images and data on read.
393#
394# If this option is disabled all the limit checking code will be disabled:
395
396option USER_LIMITS requires READ
397
398# The default settings given below for the limits mean that libpng will
399# limit the size of images or the size of data in ancillary chunks to less
400# than the specification or implementation limits. Settings have the
401# following interpretations:
402#
403# USER_WIDTH_MAX: maximum width of an image that will be read
404# USER_HEIGHT_MAX: maximum height
405# USER_CHUNK_MALLOC_MAX: maximum in-memory (decompressed) size of a single chunk
406# USER_CHUNK_CACHE_MAX: maximum number of chunks to be cached
407#
408# Only chunks that are variable in number are counted towards the
409
410# Use 0x7fffffff for unlimited
411setting USER_WIDTH_MAX default        1000000
412setting USER_HEIGHT_MAX default       1000000
413
414# Use 0 for unlimited
415setting USER_CHUNK_CACHE_MAX default     1000
416setting USER_CHUNK_MALLOC_MAX default 8000000
417
418# If this option is enabled APIs to set the above limits at run time are added;
419# without this the hardwired (compile time) limits will be used.
420option SET_USER_LIMITS requires USER_LIMITS
421
422# All of the following options relate to code capabilities for
423# processing image data before creating a PNG or after reading one.
424# You can remove these capabilities safely and still be PNG
425# conformant, however the library that results is still non-standard.
426# See the comments above about how to change options and settings.
427
428# READ options
429#
430# WARNING: in libpng 1.5 maintained configuration compatibility with earlier
431# versions.  In some cases turning off an option turned off other options, in
432# others it was ineffective unless dependent options were also turned off.
433# Libpng 1.6 changes this: in general if you turn off an option that affects
434# APIs it stays off and simply disables APIs that depend on it.
435#
436# As a result if you simply port the libpng 1.5 configuration to libpng 1.6 you
437# will probably see build failures due to missing APIs.  Fixing these failures
438# requires some, perhaps considerable, knowledge of what your libpng using
439# applications are doing, fortunately there is no great reason for you to move
440# to libpng 1.6; the new interfaces in 1.6 will take several years to become
441# popular.
442
443option READ enables READ_INTERLACING SET_OPTION
444
445# Disabling READ_16BIT does not disable reading 16-bit PNG files, but it
446# forces them to be chopped down to 8-bit, and disables any 16-bit
447# processing after that has happened.  You need to be sure to enable
448# READ_SCALE_16_TO_8 or READ_STRIP_16_TO_8 when you disable READ_16BIT for
449# this to work properly.  You should disable the other option if you need to
450# ensure a particular conversion (otherwise the app can chose.)
451
452option READ_16BIT requires READ enables 16BIT
453
454option READ_QUANTIZE requires READ
455
456option READ_TRANSFORMS requires READ
457= NO_READ_TRANSFORMS READ_TRANSFORMS_NOT_SUPPORTED
458
459# Read gamma handling.  Gamma processing is a core part of libpng and many of
460# the capabilities are dependent on libpng performing gamma correction.
461#
462# In libpng 1.6 disabling gamma processing (setting PNG_NO_READ_GAMMA)
463# consistently disables those parts of the API that depend on it.  Prior to
464# 1.6.0 this was not true; the results were unpredictable and varied between
465# releases.
466#
467# If you disable gamma processing and your program no longer compiles you need
468# to ask whether you really need the APIs that are missing.  If you do then you
469# almost certainly need the gamma processing.
470#
471# If you handle gamma issues outside libpng then you do not need the libpng
472# gamma processing; and it is an enormous waste of space.  You just need to
473# remove the use of libpng APIs that depend on it.
474option READ_GAMMA requires READ_TRANSFORMS, READ_gAMA, READ_sRGB
475
476option READ_ALPHA_MODE requires READ_TRANSFORMS, READ_GAMMA
477option READ_BACKGROUND requires READ_TRANSFORMS, READ_STRIP_ALPHA, READ_GAMMA
478option READ_BGR requires READ_TRANSFORMS
479option READ_EXPAND_16 requires READ_TRANSFORMS, READ_16BIT, READ_EXPAND
480option READ_EXPAND requires READ_TRANSFORMS
481option READ_FILLER requires READ_TRANSFORMS
482option READ_GRAY_TO_RGB requires READ_TRANSFORMS
483option READ_INVERT_ALPHA requires READ_TRANSFORMS
484option READ_INVERT requires READ_TRANSFORMS
485option READ_PACK requires READ_TRANSFORMS
486option READ_PACKSWAP requires READ_TRANSFORMS
487option READ_RGB_TO_GRAY requires READ_TRANSFORMS, READ_GAMMA enables COLORSPACE
488option READ_SCALE_16_TO_8 requires READ_TRANSFORMS
489option READ_SHIFT requires READ_TRANSFORMS
490option READ_STRIP_16_TO_8 requires READ_TRANSFORMS
491option READ_STRIP_ALPHA requires READ_TRANSFORMS
492option READ_SWAP_ALPHA requires READ_TRANSFORMS
493option READ_SWAP requires READ_TRANSFORMS, READ_16BIT
494option READ_USER_TRANSFORM requires READ_TRANSFORMS
495
496option PROGRESSIVE_READ requires READ
497option SEQUENTIAL_READ requires READ
498
499# You can define PNG_NO_PROGRESSIVE_READ if you don't do progressive reading.
500# This is not talking about interlacing capability!  You'll still have
501# interlacing unless you turn off the following which is required
502# for PNG-compliant decoders.  (In other words, do not do this - in
503# fact it can't be disabled from the command line!)
504#option READ_INTERLACING requires READ
505
506option READ_COMPOSITE_NODIV requires READ
507= NO_READ_COMPOSITE_NODIV NO_READ_COMPOSITED_NODIV
508
509# Inch conversions
510
511option INCH_CONVERSIONS
512= INCH_CONVERSIONS INCH_CONVERSIONS
513
514# API to build a grayscale palette
515# NOTE: this is not used internally by libpng at present.
516
517option BUILD_GRAYSCALE_PALETTE
518
519# WRITE options
520
521option WRITE enables WRITE_INT_FUNCTIONS
522
523# Disabling WRITE_16BIT prevents 16-bit PNG files from being
524# generated.
525option WRITE_16BIT requires WRITE enables 16BIT
526
527option WRITE_TRANSFORMS requires WRITE
528= NO_WRITE_TRANSFORMS WRITE_TRANSFORMS_NOT_SUPPORTED
529
530option WRITE_SHIFT requires WRITE_TRANSFORMS
531option WRITE_PACK requires WRITE_TRANSFORMS
532option WRITE_BGR requires WRITE_TRANSFORMS
533option WRITE_SWAP requires WRITE_TRANSFORMS, WRITE_16BIT
534option WRITE_PACKSWAP requires WRITE_TRANSFORMS
535option WRITE_INVERT requires WRITE_TRANSFORMS
536option WRITE_FILLER requires WRITE_TRANSFORMS
537option WRITE_SWAP_ALPHA requires WRITE_TRANSFORMS
538option WRITE_INVERT_ALPHA requires WRITE_TRANSFORMS
539option WRITE_USER_TRANSFORM requires WRITE_TRANSFORMS
540
541# This is not required for PNG-compliant encoders, but can cause
542# trouble if left undefined
543
544option WRITE_INTERLACING requires WRITE
545
546# Deprecated, will be removed.
547option WRITE_WEIGHTED_FILTER requires WRITE
548
549option WRITE_FLUSH requires WRITE
550
551# Note: these can be turned off explicitly if not required by the
552# apps implementing the user transforms
553option USER_TRANSFORM_PTR if READ_USER_TRANSFORM, WRITE_USER_TRANSFORM
554option USER_TRANSFORM_INFO if READ_USER_TRANSFORM, WRITE_USER_TRANSFORM
555
556# This enables API to set compression parameters for compressing
557# non-IDAT chunks (zTXt, iTXt, iCCP, and unknown chunks).  This feature
558# was added at libpng-1.5.3.
559option WRITE_CUSTOMIZE_ZTXT_COMPRESSION requires WRITE
560option WRITE_CUSTOMIZE_COMPRESSION requires WRITE
561
562# Any chunks you are not interested in, you can undef here.  The
563# ones that allocate memory may be especially important (hIST,
564# tEXt, zTXt, tRNS, pCAL).  Others will just save time and make png_info
565# a bit smaller.
566
567# The size of the png_text structure changed in libpng-1.0.6 when
568# iTXt support was added.  iTXt support was turned off by default through
569# libpng-1.2.x, to support old apps that malloc the png_text structure
570# instead of calling png_set_text() and letting libpng malloc it.  It
571# was turned on by default in libpng-1.4.0.
572
573option READ_ANCILLARY_CHUNKS requires READ
574# PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED is deprecated.
575= NO_READ_ANCILLARY_CHUNKS READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
576
577option WRITE_ANCILLARY_CHUNKS requires WRITE
578# PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED is deprecated.
579= NO_WRITE_ANCILLARY_CHUNKS WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
580
581# These options disable *all* the text chunks if turned off
582
583option TEXT disabled
584option READ_TEXT requires READ_ANCILLARY_CHUNKS enables TEXT
585option WRITE_TEXT requires WRITE_ANCILLARY_CHUNKS enables TEXT
586
587# Moved to pnglibconf.h at libpng-1.5.0
588# Feature support: in 1.4 this was in pngconf.h, but the following
589# features have no affect on the libpng API.  Add library
590# only features to the end of this list.  Add features that
591# affect the API above.  (Note: the list of chunks follows
592# the library-only settings.)
593#
594# BUILD TIME ONLY OPTIONS
595#   These options do not affect the API but rather alter how the
596#   API is implemented, they get recorded in pnglibconf.h, but
597#   can't be changed by the application.
598
599# Colorspace support (enabled as required); just the support for colorant
600# information.  Gamma support, likewise, is just support for the gamma
601# information, READ_GAMMA is required for gamma transformations (so it
602# is possible to read PNG gamma without enabling all the libpng transform
603# code - do this for applications that do their own gamma processing)
604#
605# As of 1.6.0 COLORSPACE is only useful if the application processes the
606# information; this is because the library does not do any colorspace
607# processing, it just validates the data in the PNG file.
608
609option GAMMA disabled
610option COLORSPACE enables GAMMA disabled
611
612# When an ICC profile is read, or png_set, it will be checked for a match
613# against known sRGB profiles if the sRGB handling is enabled.  The
614# PNG_sRGB_PROFILE_CHECKS setting controls how much work is done during the
615# check:
616#
617# -1: Don't do any sRGB profile checking.
618#
619#  0: Just validate the profile MD5 signature if present, otherwise use
620#     the checks in option 1.
621#
622#  1: Additionally check the length, intent and adler32 checksum of the
623#     actual data.   If enabled this will reject known profiles that have
624#     had the rendering intent in the header changed as well as other edits
625#     done without updating the checksum.  See the discussion below.
626#
627#  2: Additionally checksum all the data using the ethernet CRC32 algorithm.
628#     This makes it more difficult to fake profiles and makes it less likely
629#     to get a false positive on profiles with no signature, but is probably
630#     just a waste of time since all currently approved ICC sRGB profiles have
631#     a secure MD5 signature.
632#
633# The rendering intent.  An ICC profile stores an intended rendering intent,
634# but does not include the value in the signature.  The intent is documented
635# as the intent that should be used when combining two profiles.  The sRGB
636# profile is intended, however, to be used with any of the four defined intents.
637# For this reason the sRGB chunk includes an 'intent' to be used when displaying
638# the image (intent is really a property of the image not the profile.)
639#
640# Unfortunately the iCCP chunk does not.  It may therefore be that some
641# applications modify the intent in profiles (including sRGB profiles) to work
642# round this problem.  Selecting an option other than option '0' will cause such
643# modified profiles to be rejected.
644#
645# Security.  The use of Adler32 and CRC32 checksums does not help significantly
646# with any security issues.  It is relatively easy to produce arbitrary profiles
647# with the required checksums on current computer systems.  Nevertheless
648# security does not seem to be an issue because the only consequence of a false
649# positive is a false assertion that the profile is an sRGB profile.  This might
650# be used to hide data from libpng using applications, but it doesn't seem
651# possible to damage them.
652
653setting sRGB_PROFILE_CHECKS default 2
654
655# Artificially align memory - the code typically aligns to 8 byte
656# boundaries if this is switched on, it's a small waste of space
657# but can help (in theory) on some architectures.  Only affects
658# internal structures.  Added at libpng 1.4.0
659
660option ALIGNED_MEMORY
661
662# Buggy compilers (e.g., gcc 2.7.2.2) need PNG_NO_POINTER_INDEXING
663# See png[wr]util.c, normally this should always be *on*
664
665option POINTER_INDEXING
666
667# Other defines for things like memory and the like can go here.
668
669# BUILD TIME SETTINGS
670# Like build time options these do not affect the API, but they
671# may be useful to applications because they record details of
672# how the API will behave particularly with regard to overall
673# accuracy.
674
675# This controls how fine the quantizing gets.  As this allocates
676# a largish chunk of memory (32K), those who are not as concerned
677# with quantizing quality can decrease some or all of these.
678
679setting QUANTIZE_RED_BITS default 5
680setting QUANTIZE_GREEN_BITS default 5
681setting QUANTIZE_BLUE_BITS default 5
682
683# This controls how fine the gamma correction becomes when you
684# are only interested in 8 bits anyway.  Increasing this value
685# results in more memory being used, and more pow() functions
686# being called to fill in the gamma tables.  Don't set this value
687# less than 8, and even that may not work (I haven't tested it).
688
689setting MAX_GAMMA_8 default 11
690
691# This controls how much a difference in gamma we can tolerate before
692# we actually start doing gamma conversion, it's a fixed point value,
693# so the default below is 0.05, meaning libpng ignores corrections in
694# the range 0.95 to 1.05
695
696setting GAMMA_THRESHOLD_FIXED default 5000
697
698# Precision to use when converting a floating point value to a PNG
699# extension format string in an sCAL chunk (only relevant if the
700# floating point API is enabled)
701
702setting sCAL_PRECISION default 5
703
704# This is the size of the compression buffer, and thus the size of
705# an IDAT chunk.  Make this whatever size you feel is best for your
706# machine.  One of these will be allocated per png_struct.  When this
707# is full, it writes the data to the disk, and does some other
708# calculations.  Making this an extremely small size may slow
709# the library down, but you may want to experiment to determine
710# where it becomes significant, if you are concerned with memory
711# usage.  Note that zlib allocates at least 32Kb also.  For readers,
712# this describes the size of the buffer available to read the data in.
713# Unless this gets smaller than the size of a row (compressed),
714# it should not make much difference how big this is.
715
716setting ZBUF_SIZE default 8192
717
718# This is the size of the decompression buffer used when counting or checking
719# the decompressed size of an LZ stream from a compressed ancillary chunk; the
720# decompressed data is never used so a different size may be optimal.  This size
721# was determined using contrib/libtests/timepng.c with compressed zTXt data
722# around 11MByte in size.  Slight speed improvements (up to about 14% in
723# timepng) can be achieved by very large increases (to 32kbyte) on regular data,
724# but highly compressible data shows only around 2% improvement.   The size is
725# chosen to minimize the effects of DoS attacks based on using very large
726# amounts of highly compressible data.
727
728setting INFLATE_BUF_SIZE default 1024
729
730# This is the maximum amount of IDAT data that the sequential reader will
731# process at one time.  The setting does not affect the size of IDAT chunks
732# read, just the amount read at once.  Neither does it affect the progressive
733# reader, which processes just the amount of data the application gives it.
734# The sequential reader is currently unable to process more than one IDAT at
735# once - it has to read and process each one in turn.  There is no point setting
736# this to a value larger than the IDAT chunks typically encountered (it would
737# just waste memory) but there may be some point in reducing it below the value
738# of ZBUF_SIZE (the size of IDAT chunks written by libpng.)
739
740setting IDAT_READ_SIZE default PNG_ZBUF_SIZE
741
742# Ancillary chunks
743chunk bKGD
744chunk cHRM enables COLORSPACE
745chunk eXIf
746chunk gAMA enables GAMMA
747chunk hIST
748chunk iCCP enables COLORSPACE, GAMMA
749chunk iTXt enables TEXT
750chunk oFFs
751chunk pCAL
752chunk pHYs
753chunk sBIT
754chunk sCAL
755chunk sPLT
756chunk sRGB enables COLORSPACE, GAMMA, SET_OPTION
757chunk tEXt requires TEXT
758chunk tIME
759chunk tRNS
760chunk zTXt enables TEXT
761
762# This only affects support of the optional PLTE chunk in RGB and RGBA
763# images.  Notice that READ_ANCILLARY_CHUNKS therefore disables part
764# of the regular chunk reading too.
765
766option READ_OPT_PLTE requires READ_ANCILLARY_CHUNKS
767
768# Unknown chunk handling
769#
770# 'UNKNOWN_CHUNKS' is a global option to disable all unknown chunk handling on
771# read or write; everything else below requires it (directly or indirectly).
772option UNKNOWN_CHUNKS
773
774# There are three main options to control the ability to read and write unknown
775# chunks.  If either read option is turned on then unknown chunks will be read,
776# otherwise they are skipped.  If the write option is turned on unknown chunks
777# set by png_set_unknown_chunks will be written otherwise it is an error to call
778# that API on a write struct.
779option WRITE_UNKNOWN_CHUNKS requires WRITE requires UNKNOWN_CHUNKS
780option WRITE_UNKNOWN_CHUNKS enables STORE_UNKNOWN_CHUNKS
781
782# The first way to read user chunks is to have libpng save them for a later call
783# to png_get_unknown_chunks, the application must call
784# png_set_keep_unknown_chunks to cause this to actually happen (see png.h)
785option SAVE_UNKNOWN_CHUNKS requires READ requires SET_UNKNOWN_CHUNKS
786option SAVE_UNKNOWN_CHUNKS enables READ_UNKNOWN_CHUNKS, STORE_UNKNOWN_CHUNKS
787
788# The second approach is to use an application provided callback to process the
789# chunks, the callback can either handle the chunk entirely itself or request
790# that libpng store the chunk for later retrieval via png_get_unknown_chunks.
791#
792# NOTE: If STORE_UNKNOWN_CHUNKS is not enabled (which is the default if
793# both SAVE_UNKNOWN_CHUNKS and WRITE_UNKNOWN_CHUNKS are disabled) then a
794# 0 result from the callback will be ignored because no support for saving
795# unknown chunks has been compiled in.  The normal symptom is that your app
796# fails to compile because png_get_unknown_chunks is no longer defined in png.h.
797# If you encounter this issue simply enable STORE_UNKNOWN_CHUNKS in your build.
798#
799# Note that there is no 'WRITE_USER_CHUNKS' so the USER_CHUNKS option is always
800# the same as READ_USER_CHUNKS at present
801option READ_USER_CHUNKS requires READ, UNKNOWN_CHUNKS
802option READ_USER_CHUNKS enables READ_UNKNOWN_CHUNKS, USER_CHUNKS
803
804# Two further options are provided to allow detailed control of the handling.
805# The first enables png_set_keep_unknown_chunks; this allows the default to be
806# changed from discarding unknown chunks and allows per-chunk control.  This is
807# required to use the SAVE_UNKNOWN_CHUNKS option.  If enabled this option also
808# applies to write (see png.h), otherwise the write API simply writes all the
809# chunks it is given.
810#
811# The second option extends the unknown handling to allow known chunks to be
812# handled as though they were unknown.  This option doesn't change any APIs, it
813# merely turns on the code to check known as well as unknown chunks.
814#
815# This option no longer affects the write code.  It can be safely disabled and
816# will prevent applications stopping libpng reading known chunks.
817option SET_UNKNOWN_CHUNKS requires UNKNOWN_CHUNKS
818option HANDLE_AS_UNKNOWN requires SET_UNKNOWN_CHUNKS
819
820# The following options are derived from the above and should not be turned on
821# explicitly.
822option READ_UNKNOWN_CHUNKS requires UNKNOWN_CHUNKS disabled
823option STORE_UNKNOWN_CHUNKS requires UNKNOWN_CHUNKS disabled
824
825option CONVERT_tIME requires WRITE_ANCILLARY_CHUNKS
826# The "tm" structure is not supported on WindowsCE
827
828@#ifdef _WIN32_WCE
829@#   define PNG_NO_CONVERT_tIME
830@#endif
831
832option WRITE_FILTER requires WRITE
833
834option SAVE_INT_32 disabled
835# png_save_int_32 is required internally for writing the ancillary chunks oFFs
836# and pCAL and for both reading and writing iCCP (for the generation/checking of
837# the corresponding cHRM/gAMA chunks) if full ICC is supported.
838
839# added at libpng-1.5.4
840
841option WRITE_OPTIMIZE_CMF requires WRITE
842
843option READ_COMPRESSED_TEXT disabled
844option READ_iCCP enables READ_COMPRESSED_TEXT
845option READ_iTXt enables READ_COMPRESSED_TEXT
846option READ_zTXt enables READ_COMPRESSED_TEXT
847
848option WRITE_oFFs enables SAVE_INT_32
849option WRITE_pCAL enables SAVE_INT_32
850option WRITE_cHRM enables SAVE_INT_32
851
852option WRITE_COMPRESSED_TEXT disabled
853option WRITE_iCCP enables WRITE_COMPRESSED_TEXT
854option WRITE_iTXt enables WRITE_COMPRESSED_TEXT
855option WRITE_zTXt enables WRITE_COMPRESSED_TEXT
856
857# Turn this off to disable png_read_png() and png_write_png() and
858# leave the row_pointers member out of the info structure.
859
860option INFO_IMAGE
861
862# added at libpng-1.5.10
863# Turn this off to disable warning about invalid palette index and
864# leave the num_palette_max member out of the png structure.
865
866option CHECK_FOR_INVALID_INDEX enables READ_CHECK_FOR_INVALID_INDEX
867option CHECK_FOR_INVALID_INDEX enables WRITE_CHECK_FOR_INVALID_INDEX
868option READ_CHECK_FOR_INVALID_INDEX requires READ, CHECK_FOR_INVALID_INDEX
869option WRITE_CHECK_FOR_INVALID_INDEX requires WRITE, CHECK_FOR_INVALID_INDEX
870
871# added at libpng-1.5.15
872option GET_PALETTE_MAX enables READ_GET_PALETTE_MAX WRITE_GET_PALETTE_MAX
873option READ_GET_PALETTE_MAX requires READ_CHECK_FOR_INVALID_INDEX disabled
874option WRITE_GET_PALETTE_MAX requires WRITE_CHECK_FOR_INVALID_INDEX disabled
875
876# Simplified API options (added at libpng-1.6.0)
877#  In libpng 1.6.8 the handling of these options was changed to used 'requires'
878#  throughout, so that disabling some of the low level support always disables
879#  the base simplified read/write API.  This much simplifies the handling and
880#  makes 'everything = off' work in a more intuitive way.  It eliminates a
881#  previously reported feature that APIs previously enabled by the simplified
882#  API couldn't be turned off without explicitly turning off the simplified
883#  APIs.
884#
885# Read:
886option SIMPLIFIED_READ,
887   requires SEQUENTIAL_READ, READ_TRANSFORMS, SETJMP, BENIGN_ERRORS,
888      READ_EXPAND, READ_16BIT, READ_EXPAND_16, READ_SCALE_16_TO_8,
889      READ_RGB_TO_GRAY, READ_ALPHA_MODE, READ_BACKGROUND, READ_STRIP_ALPHA,
890      READ_FILLER, READ_SWAP, READ_PACK, READ_GRAY_TO_RGB, READ_GAMMA,
891      READ_tRNS, READ_bKGD, READ_gAMA, READ_cHRM, READ_sRGB, READ_sBIT
892
893# AFIRST and BGR read options:
894#  Prior to libpng 1.6.8 these were disabled but switched on if the low level
895#  libpng routines that do the swaps were enabled.  This worked but was
896#  confusing.  In libpng 1.6.8 the options were changed to simple 'requires'
897#  and are enabled by default.  This should work the same way in practice.
898option SIMPLIFIED_READ_AFIRST enables FORMAT_AFIRST,
899   requires SIMPLIFIED_READ READ_SWAP_ALPHA
900
901option SIMPLIFIED_READ_BGR enables FORMAT_BGR,
902   requires SIMPLIFIED_READ READ_BGR
903
904# Write:
905option SIMPLIFIED_WRITE,
906   requires WRITE, SETJMP, WRITE_SWAP, WRITE_PACK,
907      WRITE_tRNS, WRITE_gAMA, WRITE_sRGB, WRITE_cHRM
908
909# 1.6.22: allow simplified write without stdio support:
910option SIMPLIFIED_WRITE_STDIO requires SIMPLIFIED_WRITE STDIO
911
912option SIMPLIFIED_WRITE_AFIRST enables FORMAT_AFIRST,
913   requires SIMPLIFIED_WRITE WRITE_SWAP_ALPHA
914
915option SIMPLIFIED_WRITE_BGR enables FORMAT_BGR,
916   requires SIMPLIFIED_WRITE WRITE_BGR
917
918# Formats:
919option FORMAT_AFIRST disabled
920option FORMAT_BGR disabled
921