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