~ubuntu-branches/ubuntu/precise/libpng/precise : revision 1.1.14

1

libpng.txt - A description on how to use and modify libpng

2

3

libpng version 1.2.46 - July 9, 2011

4

Updated and distributed by Glenn Randers-Pehrson

5

6

7

8

This document is released under the libpng license.

9

For conditions of distribution and use, see the disclaimer

10

and license in png.h

11

12

Based on:

13

14

libpng versions 0.97, January 1998, through 1.2.46 - July 9, 2011

15

Updated and distributed by Glenn Randers-Pehrson

16

17

18

libpng 1.0 beta 6 version 0.96 May 28, 1997

19

Updated and distributed by Andreas Dilger

20

21

22

libpng 1.0 beta 2 - version 0.88 January 26, 1996

23

For conditions of distribution and use, see copyright

24

25

Schalnat, Group 42, Inc.

26

27

Updated/rewritten per request in the libpng FAQ

28

29

December 18, 1995 & January 20, 1996

30

31

I. Introduction

32

33

This file describes how to use and modify the PNG reference library

34

(known as libpng) for your own use. There are five sections to this

35

file: introduction, structures, reading, writing, and modification and

36

configuration notes for various special platforms. In addition to this

37

file, example.c is a good starting point for using the library, as

38

it is heavily commented and should include everything most people

39

will need. We assume that libpng is already installed; see the

40

INSTALL file for instructions on how to install libpng.

41

42

For examples of libpng usage, see the files "example.c", "pngtest.c",

43

and the files in the "contrib" directory, all of which are included in

44

the libpng distribution.

45

46

Libpng was written as a companion to the PNG specification, as a way

47

of reducing the amount of time and effort it takes to support the PNG

48

file format in application programs.

49

50

The PNG specification (second edition), November 2003, is available as

51

a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at

52

<http://www.w3.org/TR/2003/REC-PNG-20031110/

53

The W3C and ISO documents have identical technical content.

54

55

The PNG-1.2 specification is available at

56

<http://www.libpng.org/pub/png/documents/>. It is technically equivalent

57

to the PNG specification (second edition) but has some additional material.

58

59

The PNG-1.0 specification is available

60

as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a

61

W3C Recommendation <http://www.w3.org/TR/REC.png.html>.

62

63

Some additional chunks are described in the special-purpose public chunks

64

documents at <http://www.libpng.org/pub/png/documents/>.

65

66

Other information

67

about PNG, and the latest version of libpng, can be found at the PNG home

68

page, <http://www.libpng.org/pub/png/>.

69

70

Most users will not have to modify the library significantly; advanced

71

users may want to modify it more. All attempts were made to make it as

72

complete as possible, while keeping the code easy to understand.

73

Currently, this library only supports C. Support for other languages

74

is being considered.

75

76

Libpng has been designed to handle multiple sessions at one time,

77

to be easily modifiable, to be portable to the vast majority of

78

machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy

79

to use. The ultimate goal of libpng is to promote the acceptance of

80

the PNG file format in whatever way possible. While there is still

81

work to be done (see the TODO file), libpng should cover the

82

majority of the needs of its users.

83

84

Libpng uses zlib for its compression and decompression of PNG files.

85

Further information about zlib, and the latest version of zlib, can

86

be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.

87

The zlib compression utility is a general purpose utility that is

88

useful for more than PNG files, and can be used without libpng.

89

See the documentation delivered with zlib for more details.

90

You can usually find the source files for the zlib utility wherever you

91

find the libpng source files.

92

93

Libpng is thread safe, provided the threads are using different

94

instances of the structures. Each thread should have its own

95

png_struct and png_info instances, and thus its own image.

96

Libpng does not protect itself against two threads using the

97

same instance of a structure.

98

99

II. Structures

100

101

There are two main structures that are important to libpng, png_struct

102

and png_info. The first, png_struct, is an internal structure that

103

will not, for the most part, be used by a user except as the first

104

variable passed to every libpng function call.

105

106

The png_info structure is designed to provide information about the

107

PNG file. At one time, the fields of png_info were intended to be

108

directly accessible to the user. However, this tended to cause problems

109

with applications using dynamically loaded libraries, and as a result

110

a set of interface functions for png_info (the png_get_*() and png_set_*()

111

functions) was developed. The fields of png_info are still available for

112

older applications, but it is suggested that applications use the new

113

interfaces if at all possible.

114

115

Applications that do make direct access to the members of png_struct (except

116

for png_ptr->jmpbuf) must be recompiled whenever the library is updated,

117

and applications that make direct access to the members of png_info must

118

be recompiled if they were compiled or loaded with libpng version 1.0.6,

119

in which the members were in a different order. In version 1.0.7, the

120

members of the png_info structure reverted to the old order, as they were

121

in versions 0.97c through 1.0.5. Starting with version 2.0.0, both

122

structures are going to be hidden, and the contents of the structures will

123

only be accessible through the png_get/png_set functions.

124

125

The png.h header file is an invaluable reference for programming with libpng.

126

And while I'm on the topic, make sure you include the libpng header file:

127

128

#include <png.h>

129

130

III. Reading

131

132

We'll now walk you through the possible functions to call when reading

133

in a PNG file sequentially, briefly explaining the syntax and purpose

134

of each one. See example.c and png.h for more detail. While

135

progressive reading is covered in the next section, you will still

136

need some of the functions discussed in this section to read a PNG

137

file.

138

139

Setup

140

141

You will want to do the I/O initialization(*) before you get into libpng,

142

so if it doesn't work, you don't have much to undo. Of course, you

143

will also want to insure that you are, in fact, dealing with a PNG

144

file. Libpng provides a simple check to see if a file is a PNG file.

145

To use it, pass in the first 1 to 8 bytes of the file to the function

146

png_sig_cmp(), and it will return 0 (false) if the bytes match the

147

corresponding bytes of the PNG signature, or nonzero (true) otherwise.

148

Of course, the more bytes you pass in, the greater the accuracy of the

149

prediction.

150

151

If you are intending to keep the file pointer open for use in libpng,

152

you must ensure you don't read more than 8 bytes from the beginning

153

of the file, and you also have to make a call to png_set_sig_bytes_read()

154

with the number of bytes you read from the beginning. Libpng will

155

then only check the bytes (if any) that your program didn't read.

156

157

(*): If you are not using the standard I/O functions, you will need

158

to replace them with custom functions. See the discussion under

159

Customizing libpng.

160

161

162

FILE *fp = fopen(file_name, "rb");

163

if (!fp)

164

{

165

return (ERROR);

166

}

167

fread(header, 1, number, fp);

168

is_png = !png_sig_cmp(header, 0, number);

169

if (!is_png)

170

{

171

return (NOT_PNG);

172

}

173

174

175

Next, png_struct and png_info need to be allocated and initialized. In

176

order to ensure that the size of these structures is correct even with a

177

dynamically linked libpng, there are functions to initialize and

178

allocate the structures. We also pass the library version, optional

179

pointers to error handling functions, and a pointer to a data struct for

180

use by the error functions, if necessary (the pointer and functions can

181

be NULL if the default error handlers are to be used). See the section

182

on Changes to Libpng below regarding the old initialization functions.

183

The structure allocation functions quietly return NULL if they fail to

184

create the structure, so your application should check for that.

185

186

png_structp png_ptr = png_create_read_struct

187

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

188

user_error_fn, user_warning_fn);

189

if (!png_ptr)

190

return (ERROR);

191

192

png_infop info_ptr = png_create_info_struct(png_ptr);

193

if (!info_ptr)

194

{

195

png_destroy_read_struct(&png_ptr,

196

(png_infopp)NULL, (png_infopp)NULL);

197

return (ERROR);

198

}

199

200

png_infop end_info = png_create_info_struct(png_ptr);

201

if (!end_info)

202

{

203

png_destroy_read_struct(&png_ptr, &info_ptr,

204

(png_infopp)NULL);

205

return (ERROR);

206

}

207

208

If you want to use your own memory allocation routines,

209

define PNG_USER_MEM_SUPPORTED and use

210

png_create_read_struct_2() instead of png_create_read_struct():

211

212

png_structp png_ptr = png_create_read_struct_2

213

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

214

user_error_fn, user_warning_fn, (png_voidp)

215

user_mem_ptr, user_malloc_fn, user_free_fn);

216

217

The error handling routines passed to png_create_read_struct()

218

and the memory alloc/free routines passed to png_create_struct_2()

219

are only necessary if you are not using the libpng supplied error

220

handling and memory alloc/free functions.

221

222

When libpng encounters an error, it expects to longjmp back

223

to your routine. Therefore, you will need to call setjmp and pass

224

your png_jmpbuf(png_ptr). If you read the file from different

225

routines, you will need to update the jmpbuf field every time you enter

226

a new routine that will call a png_*() function.

227

228

See your documentation of setjmp/longjmp for your compiler for more

229

information on setjmp/longjmp. See the discussion on libpng error

230

handling in the Customizing Libpng section below for more information

231

on the libpng error handling. If an error occurs, and libpng longjmp's

232

back to your setjmp, you will want to call png_destroy_read_struct() to

233

free any memory.

234

235

if (setjmp(png_jmpbuf(png_ptr)))

236

{

237

png_destroy_read_struct(&png_ptr, &info_ptr,

238

&end_info);

239

fclose(fp);

240

return (ERROR);

241

}

242

243

If you would rather avoid the complexity of setjmp/longjmp issues,

244

you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case

245

errors will result in a call to PNG_ABORT() which defaults to abort().

246

247

Now you need to set up the input code. The default for libpng is to

248

use the C function fread(). If you use this, you will need to pass a

249

valid FILE * in the function png_init_io(). Be sure that the file is

250

opened in binary mode. If you wish to handle reading data in another

251

way, you need not call the png_init_io() function, but you must then

252

implement the libpng I/O methods discussed in the Customizing Libpng

253

section below.

254

255

png_init_io(png_ptr, fp);

256

257

If you had previously opened the file and read any of the signature from

258

the beginning in order to see if this was a PNG file, you need to let

259

libpng know that there are some bytes missing from the start of the file.

260

261

png_set_sig_bytes(png_ptr, number);

262

263

Setting up callback code

264

265

You can set up a callback function to handle any unknown chunks in the

266

input stream. You must supply the function

267

268

read_chunk_callback(png_ptr ptr,

269

png_unknown_chunkp chunk);

270

{

271

/* The unknown chunk structure contains your

272

chunk data, along with similar data for any other

273

unknown chunks: */

274

275

png_byte name[5];

276

png_byte *data;

277

png_size_t size;

278

279

/* Note that libpng has already taken care of

280

the CRC handling */

281

282

/* put your code here. Search for your chunk in the

283

unknown chunk structure, process it, and return one

284

of the following: */

285

286

return (-n); /* chunk had an error */

287

return (0); /* did not recognize */

288

return (n); /* success */

289

}

290

291

(You can give your function another name that you like instead of

292

"read_chunk_callback")

293

294

To inform libpng about your function, use

295

296

png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,

297

read_chunk_callback);

298

299

This names not only the callback function, but also a user pointer that

300

you can retrieve with

301

302

png_get_user_chunk_ptr(png_ptr);

303

304

If you call the png_set_read_user_chunk_fn() function, then all unknown

305

chunks will be saved when read, in case your callback function will need

306

one or more of them. This behavior can be changed with the

307

png_set_keep_unknown_chunks() function, described below.

308

309

At this point, you can set up a callback function that will be

310

called after each row has been read, which you can use to control

311

a progress meter or the like. It's demonstrated in pngtest.c.

312

You must supply a function

313

314

void read_row_callback(png_ptr ptr, png_uint_32 row,

315

int pass);

316

{

317

/* put your code here */

318

}

319

320

(You can give it another name that you like instead of "read_row_callback")

321

322

To inform libpng about your function, use

323

324

png_set_read_status_fn(png_ptr, read_row_callback);

325

326

Unknown-chunk handling

327

328

Now you get to set the way the library processes unknown chunks in the

329

input PNG stream. Both known and unknown chunks will be read. Normal

330

behavior is that known chunks will be parsed into information in

331

various info_ptr members while unknown chunks will be discarded. This

332

behavior can be wasteful if your application will never use some known

333

chunk types. To change this, you can call:

334

335

png_set_keep_unknown_chunks(png_ptr, keep,

336

chunk_list, num_chunks);

337

keep - 0: default unknown chunk handling

338

1: ignore; do not keep

339

2: keep only if safe-to-copy

340

3: keep even if unsafe-to-copy

341

You can use these definitions:

342

PNG_HANDLE_CHUNK_AS_DEFAULT 0

343

PNG_HANDLE_CHUNK_NEVER 1

344

PNG_HANDLE_CHUNK_IF_SAFE 2

345

PNG_HANDLE_CHUNK_ALWAYS 3

346

chunk_list - list of chunks affected (a byte string,

347

five bytes per chunk, NULL or '\0' if

348

num_chunks is 0)

349

num_chunks - number of chunks affected; if 0, all

350

unknown chunks are affected. If nonzero,

351

only the chunks in the list are affected

352

353

Unknown chunks declared in this way will be saved as raw data onto a

354

list of png_unknown_chunk structures. If a chunk that is normally

355

known to libpng is named in the list, it will be handled as unknown,

356

according to the "keep" directive. If a chunk is named in successive

357

instances of png_set_keep_unknown_chunks(), the final instance will

358

take precedence. The IHDR and IEND chunks should not be named in

359

chunk_list; if they are, libpng will process them normally anyway.

360

361

Here is an example of the usage of png_set_keep_unknown_chunks(),

362

where the private "vpAg" chunk will later be processed by a user chunk

363

callback function:

364

365

png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};

366

367

#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)

368

png_byte unused_chunks[]=

369

{

370

104, 73, 83, 84, (png_byte) '\0', /* hIST */

371

105, 84, 88, 116, (png_byte) '\0', /* iTXt */

372

112, 67, 65, 76, (png_byte) '\0', /* pCAL */

373

115, 67, 65, 76, (png_byte) '\0', /* sCAL */

374

115, 80, 76, 84, (png_byte) '\0', /* sPLT */

375

116, 73, 77, 69, (png_byte) '\0', /* tIME */

376

};

377

#endif

378

379

...

380

381

#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)

382

/* ignore all unknown chunks: */

383

png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);

384

/* except for vpAg: */

385

png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);

386

/* also ignore unused known chunks: */

387

png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,

388

(int)sizeof(unused_chunks)/5);

389

#endif

390

391

User limits

392

393

The PNG specification allows the width and height of an image to be as

394

large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.

395

Since very few applications really need to process such large images,

396

we have imposed an arbitrary 1-million limit on rows and columns.

397

Larger images will be rejected immediately with a png_error() call. If

398

you wish to override this limit, you can use

399

400

png_set_user_limits(png_ptr, width_max, height_max);

401

402

to set your own limits, or use width_max = height_max = 0x7fffffffL

403

to allow all valid dimensions (libpng may reject some very large images

404

anyway because of potential buffer overflow conditions).

405

406

You should put this statement after you create the PNG structure and

407

before calling png_read_info(), png_read_png(), or png_process_data().

408

If you need to retrieve the limits that are being applied, use

409

410

width_max = png_get_user_width_max(png_ptr);

411

height_max = png_get_user_height_max(png_ptr);

412

413

The PNG specification sets no limit on the number of ancillary chunks

414

allowed in a PNG datastream. You can impose a limit on the total number

415

of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with

416

417

png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);

418

419

where 0x7fffffffL means unlimited. You can retrieve this limit with

420

421

chunk_cache_max = png_get_chunk_cache_max(png_ptr);

422

423

This limit also applies to the number of buffers that can be allocated

424

by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.

425

426

The high-level read interface

427

428

At this point there are two ways to proceed; through the high-level

429

read interface, or through a sequence of low-level read operations.

430

You can use the high-level interface if (a) you are willing to read

431

the entire image into memory, and (b) the input transformations

432

you want to do are limited to the following set:

433

434

PNG_TRANSFORM_IDENTITY No transformation

435

PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to

436

8 bits

437

PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel

438

PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit

439

samples to bytes

440

PNG_TRANSFORM_PACKSWAP Change order of packed

441

pixels to LSB first

442

PNG_TRANSFORM_EXPAND Perform set_expand()

443

PNG_TRANSFORM_INVERT_MONO Invert monochrome images

444

PNG_TRANSFORM_SHIFT Normalize pixels to the

445

sBIT depth

446

PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA

447

to BGRA

448

PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA

449

to AG

450

PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity

451

to transparency

452

PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples

453

PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples

454

to RGB (or GA to RGBA)

455

456

(This excludes setting a background color, doing gamma transformation,

457

dithering, and setting filler.) If this is the case, simply do this:

458

459

png_read_png(png_ptr, info_ptr, png_transforms, NULL)

460

461

where png_transforms is an integer containing the bitwise OR of some

462

set of transformation flags. This call is equivalent to png_read_info(),

463

followed the set of transformations indicated by the transform mask,

464

then png_read_image(), and finally png_read_end().

465

466

(The final parameter of this call is not yet used. Someday it might point

467

to transformation parameters required by some future input transform.)

468

469

You must use png_transforms and not call any png_set_transform() functions

470

when you use png_read_png().

471

472

After you have called png_read_png(), you can retrieve the image data

473

with

474

475

row_pointers = png_get_rows(png_ptr, info_ptr);

476

477

where row_pointers is an array of pointers to the pixel data for each row:

478

479

png_bytep row_pointers[height];

480

481

If you know your image size and pixel size ahead of time, you can allocate

482

row_pointers prior to calling png_read_png() with

483

484

if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))

485

png_error (png_ptr,

486

"Image is too tall to process in memory");

487

if (width > PNG_UINT_32_MAX/pixel_size)

488

png_error (png_ptr,

489

"Image is too wide to process in memory");

490

row_pointers = png_malloc(png_ptr,

491

height*png_sizeof(png_bytep));

492

for (int i=0; i<height, i++)

493

row_pointers[i]=NULL; /* security precaution */

494

for (int i=0; i<height, i++)

495

row_pointers[i]=png_malloc(png_ptr,

496

width*pixel_size);

497

png_set_rows(png_ptr, info_ptr, &row_pointers);

498

499

Alternatively you could allocate your image in one big block and define

500

row_pointers[i] to point into the proper places in your block.

501

502

If you use png_set_rows(), the application is responsible for freeing

503

row_pointers (and row_pointers[i], if they were separately allocated).

504

505

If you don't allocate row_pointers ahead of time, png_read_png() will

506

do it, and it'll be free'ed when you call png_destroy_*().

507

508

The low-level read interface

509

510

If you are going the low-level route, you are now ready to read all

511

the file information up to the actual image data. You do this with a

512

call to png_read_info().

513

514

png_read_info(png_ptr, info_ptr);

515

516

This will process all chunks up to but not including the image data.

517

518

Querying the info structure

519

520

Functions are used to get the information from the info_ptr once it

521

has been read. Note that these fields may not be completely filled

522

in until png_read_end() has read the chunk data following the image.

523

524

png_get_IHDR(png_ptr, info_ptr, &width, &height,

525

&bit_depth, &color_type, &interlace_type,

526

&compression_type, &filter_method);

527

528

width - holds the width of the image

529

in pixels (up to 2^31).

530

height - holds the height of the image

531

in pixels (up to 2^31).

532

bit_depth - holds the bit depth of one of the

533

image channels. (valid values are

534

1, 2, 4, 8, 16 and depend also on

535

the color_type. See also

536

significant bits (sBIT) below).

537

color_type - describes which color/alpha channels

538

are present.

539

PNG_COLOR_TYPE_GRAY

540

(bit depths 1, 2, 4, 8, 16)

541

PNG_COLOR_TYPE_GRAY_ALPHA

542

(bit depths 8, 16)

543

PNG_COLOR_TYPE_PALETTE

544

(bit depths 1, 2, 4, 8)

545

PNG_COLOR_TYPE_RGB

546

(bit_depths 8, 16)

547

PNG_COLOR_TYPE_RGB_ALPHA

548

(bit_depths 8, 16)

549

550

PNG_COLOR_MASK_PALETTE

551

PNG_COLOR_MASK_COLOR

552

PNG_COLOR_MASK_ALPHA

553

554

filter_method - (must be PNG_FILTER_TYPE_BASE

555

for PNG 1.0, and can also be

556

PNG_INTRAPIXEL_DIFFERENCING if

557

the PNG datastream is embedded in

558

a MNG-1.0 datastream)

559

compression_type - (must be PNG_COMPRESSION_TYPE_BASE

560

for PNG 1.0)

561

interlace_type - (PNG_INTERLACE_NONE or

562

PNG_INTERLACE_ADAM7)

563

564

Any or all of interlace_type, compression_type, or

565

filter_method can be NULL if you are

566

not interested in their values.

567

568

Note that png_get_IHDR() returns 32-bit data into

569

the application's width and height variables.

570

This is an unsafe situation if these are 16-bit

571

variables. In such situations, the

572

png_get_image_width() and png_get_image_height()

573

functions described below are safer.

574

575

width = png_get_image_width(png_ptr,

576

info_ptr);

577

height = png_get_image_height(png_ptr,

578

info_ptr);

579

bit_depth = png_get_bit_depth(png_ptr,

580

info_ptr);

581

color_type = png_get_color_type(png_ptr,

582

info_ptr);

583

filter_method = png_get_filter_type(png_ptr,

584

info_ptr);

585

compression_type = png_get_compression_type(png_ptr,

586

info_ptr);

587

interlace_type = png_get_interlace_type(png_ptr,

588

info_ptr);

589

590

channels = png_get_channels(png_ptr, info_ptr);

591

channels - number of channels of info for the

592

color type (valid values are 1 (GRAY,

593

PALETTE), 2 (GRAY_ALPHA), 3 (RGB),

594

4 (RGB_ALPHA or RGB + filler byte))

595

rowbytes = png_get_rowbytes(png_ptr, info_ptr);

596

rowbytes - number of bytes needed to hold a row

597

598

signature = png_get_signature(png_ptr, info_ptr);

599

signature - holds the signature read from the

600

file (if any). The data is kept in

601

the same offset it would be if the

602

whole signature were read (i.e. if an

603

application had already read in 4

604

bytes of signature before starting

605

libpng, the remaining 4 bytes would

606

be in signature[4] through signature[7]

607

(see png_set_sig_bytes())).

608

609

These are also important, but their validity depends on whether the chunk

610

has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and

611

png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the

612

data has been read, or zero if it is missing. The parameters to the

613

png_get_<chunk> are set directly if they are simple data types, or a

614

pointer into the info_ptr is returned for any complex types.

615

616

png_get_PLTE(png_ptr, info_ptr, &palette,

617

&num_palette);

618

palette - the palette for the file

619

(array of png_color)

620

num_palette - number of entries in the palette

621

622

png_get_gAMA(png_ptr, info_ptr, &gamma);

623

gamma - the gamma the file is written

624

at (PNG_INFO_gAMA)

625

626

png_get_sRGB(png_ptr, info_ptr, &srgb_intent);

627

srgb_intent - the rendering intent (PNG_INFO_sRGB)

628

The presence of the sRGB chunk

629

means that the pixel data is in the

630

sRGB color space. This chunk also

631

implies specific values of gAMA and

632

cHRM.

633

634

png_get_iCCP(png_ptr, info_ptr, &name,

635

&compression_type, &profile, &proflen);

636

name - The profile name.

637

compression - The compression type; always

638

PNG_COMPRESSION_TYPE_BASE for PNG 1.0.

639

You may give NULL to this argument to

640

ignore it.

641

profile - International Color Consortium color

642

profile data. May contain NULs.

643

proflen - length of profile data in bytes.

644

645

png_get_sBIT(png_ptr, info_ptr, &sig_bit);

646

sig_bit - the number of significant bits for

647

(PNG_INFO_sBIT) each of the gray,

648

red, green, and blue channels,

649

whichever are appropriate for the

650

given color type (png_color_16)

651

652

png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,

653

&trans_values);

654

trans - array of transparent

655

entries for palette (PNG_INFO_tRNS)

656

trans_values - graylevel or color sample values of

657

the single transparent color for

658

non-paletted images (PNG_INFO_tRNS)

659

num_trans - number of transparent entries

660

(PNG_INFO_tRNS)

661

662

png_get_hIST(png_ptr, info_ptr, &hist);

663

(PNG_INFO_hIST)

664

hist - histogram of palette (array of

665

png_uint_16)

666

667

png_get_tIME(png_ptr, info_ptr, &mod_time);

668

mod_time - time image was last modified

669

(PNG_VALID_tIME)

670

671

png_get_bKGD(png_ptr, info_ptr, &background);

672

background - background color (PNG_VALID_bKGD)

673

valid 16-bit red, green and blue

674

values, regardless of color_type

675

676

num_comments = png_get_text(png_ptr, info_ptr,

677

&text_ptr, &num_text);

678

num_comments - number of comments

679

text_ptr - array of png_text holding image

680

comments

681

text_ptr[i].compression - type of compression used

682

on "text" PNG_TEXT_COMPRESSION_NONE

683

PNG_TEXT_COMPRESSION_zTXt

684

PNG_ITXT_COMPRESSION_NONE

685

PNG_ITXT_COMPRESSION_zTXt

686

text_ptr[i].key - keyword for comment. Must contain

687

1-79 characters.

688

text_ptr[i].text - text comments for current

689

keyword. Can be empty.

690

text_ptr[i].text_length - length of text string,

691

after decompression, 0 for iTXt

692

text_ptr[i].itxt_length - length of itxt string,

693

after decompression, 0 for tEXt/zTXt

694

text_ptr[i].lang - language of comment (empty

695

string for unknown).

696

text_ptr[i].lang_key - keyword in UTF-8

697

(empty string for unknown).

698

Note that the itxt_length, lang, and lang_key

699

members of the text_ptr structure only exist

700

when the library is built with iTXt chunk support.

701

702

num_text - number of comments (same as

703

num_comments; you can put NULL here

704

to avoid the duplication)

705

Note while png_set_text() will accept text, language,

706

and translated keywords that can be NULL pointers, the

707

structure returned by png_get_text will always contain

708

regular zero-terminated C strings. They might be

709

empty strings but they will never be NULL pointers.

710

711

num_spalettes = png_get_sPLT(png_ptr, info_ptr,

712

&palette_ptr);

713

palette_ptr - array of palette structures holding

714

contents of one or more sPLT chunks

715

read.

716

num_spalettes - number of sPLT chunks read.

717

718

png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,

719

&unit_type);

720

offset_x - positive offset from the left edge

721

of the screen

722

offset_y - positive offset from the top edge

723

of the screen

724

unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER

725

726

png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,

727

&unit_type);

728

res_x - pixels/unit physical resolution in

729

x direction

730

res_y - pixels/unit physical resolution in

731

x direction

732

unit_type - PNG_RESOLUTION_UNKNOWN,

733

PNG_RESOLUTION_METER

734

735

png_get_sCAL(png_ptr, info_ptr, &unit, &width,

736

&height)

737

unit - physical scale units (an integer)

738

width - width of a pixel in physical scale units

739

height - height of a pixel in physical scale units

740

(width and height are doubles)

741

742

png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,

743

&height)

744

unit - physical scale units (an integer)

745

width - width of a pixel in physical scale units

746

height - height of a pixel in physical scale units

747

(width and height are strings like "2.54")

748

749

num_unknown_chunks = png_get_unknown_chunks(png_ptr,

750

info_ptr, &unknowns)

751

unknowns - array of png_unknown_chunk

752

structures holding unknown chunks

753

unknowns[i].name - name of unknown chunk

754

unknowns[i].data - data of unknown chunk

755

unknowns[i].size - size of unknown chunk's data

756

unknowns[i].location - position of chunk in file

757

758

The value of "i" corresponds to the order in which the

759

chunks were read from the PNG file or inserted with the

760

png_set_unknown_chunks() function.

761

762

The data from the pHYs chunk can be retrieved in several convenient

763

forms:

764

765

res_x = png_get_x_pixels_per_meter(png_ptr,

766

info_ptr)

767

res_y = png_get_y_pixels_per_meter(png_ptr,

768

info_ptr)

769

res_x_and_y = png_get_pixels_per_meter(png_ptr,

770

info_ptr)

771

res_x = png_get_x_pixels_per_inch(png_ptr,

772

info_ptr)

773

res_y = png_get_y_pixels_per_inch(png_ptr,

774

info_ptr)

775

res_x_and_y = png_get_pixels_per_inch(png_ptr,

776

info_ptr)

777

aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,

778

info_ptr)

779

780

(Each of these returns 0 [signifying "unknown"] if

781

the data is not present or if res_x is 0;

782

res_x_and_y is 0 if res_x != res_y)

783

784

The data from the oFFs chunk can be retrieved in several convenient

785

forms:

786

787

x_offset = png_get_x_offset_microns(png_ptr, info_ptr);

788

y_offset = png_get_y_offset_microns(png_ptr, info_ptr);

789

x_offset = png_get_x_offset_inches(png_ptr, info_ptr);

790

y_offset = png_get_y_offset_inches(png_ptr, info_ptr);

791

792

(Each of these returns 0 [signifying "unknown" if both

793

x and y are 0] if the data is not present or if the

794

chunk is present but the unit is the pixel)

795

796

For more information, see the png_info definition in png.h and the

797

PNG specification for chunk contents. Be careful with trusting

798

rowbytes, as some of the transformations could increase the space

799

needed to hold a row (expand, filler, gray_to_rgb, etc.).

800

See png_read_update_info(), below.

801

802

A quick word about text_ptr and num_text. PNG stores comments in

803

keyword/text pairs, one pair per chunk, with no limit on the number

804

of text chunks, and a 2^31 byte limit on their size. While there are

805

suggested keywords, there is no requirement to restrict the use to these

806

strings. It is strongly suggested that keywords and text be sensible

807

to humans (that's the point), so don't use abbreviations. Non-printing

808

symbols are not allowed. See the PNG specification for more details.

809

There is also no requirement to have text after the keyword.

810

811

Keywords should be limited to 79 Latin-1 characters without leading or

812

trailing spaces, but non-consecutive spaces are allowed within the

813

keyword. It is possible to have the same keyword any number of times.

814

The text_ptr is an array of png_text structures, each holding a

815

pointer to a language string, a pointer to a keyword and a pointer to

816

a text string. The text string, language code, and translated

817

keyword may be empty or NULL pointers. The keyword/text

818

pairs are put into the array in the order that they are received.

819

However, some or all of the text chunks may be after the image, so, to

820

make sure you have read all the text chunks, don't mess with these

821

until after you read the stuff after the image. This will be

822

mentioned again below in the discussion that goes with png_read_end().

823

824

Input transformations

825

826

After you've read the header information, you can set up the library

827

to handle any special transformations of the image data. The various

828

ways to transform the data will be described in the order that they

829

should occur. This is important, as some of these change the color

830

type and/or bit depth of the data, and some others only work on

831

certain color types and bit depths. Even though each transformation

832

checks to see if it has data that it can do something with, you should

833

make sure to only enable a transformation if it will be valid for the

834

data. For example, don't swap red and blue on grayscale data.

835

836

The colors used for the background and transparency values should be

837

supplied in the same format/depth as the current image data. They

838

are stored in the same format/depth as the image data in a bKGD or tRNS

839

chunk, so this is what libpng expects for this data. The colors are

840

transformed to keep in sync with the image data when an application

841

calls the png_read_update_info() routine (see below).

842

843

Data will be decoded into the supplied row buffers packed into bytes

844

unless the library has been told to transform it into another format.

845

For example, 4 bit/pixel paletted or grayscale data will be returned

846

2 pixels/byte with the leftmost pixel in the high-order bits of the

847

byte, unless png_set_packing() is called. 8-bit RGB data will be stored

848

in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()

849

is called to insert filler bytes, either before or after each RGB triplet.

850

16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant

851

byte of the color value first, unless png_set_strip_16() is called to

852

transform it to regular RGB RGB triplets, or png_set_filler() or

853

png_set_add alpha() is called to insert filler bytes, either before or

854

after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can

855

be modified with

856

png_set_filler(), png_set_add_alpha(), or png_set_strip_16().

857

858

The following code transforms grayscale images of less than 8 to 8 bits,

859

changes paletted images to RGB, and adds a full alpha channel if there is

860

transparency information in a tRNS chunk. This is most useful on

861

grayscale images with bit depths of 2 or 4 or if there is a multiple-image

862

viewing application that wishes to treat all images in the same way.

863

864

if (color_type == PNG_COLOR_TYPE_PALETTE)

865

png_set_palette_to_rgb(png_ptr);

866

867

if (color_type == PNG_COLOR_TYPE_GRAY &&

868

bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);

869

870

if (png_get_valid(png_ptr, info_ptr,

871

PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);

872

873

These three functions are actually aliases for png_set_expand(), added

874

in libpng version 1.0.4, with the function names expanded to improve code

875

readability. In some future version they may actually do different

876

things.

877

878

As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was

879

added. It expands the sample depth without changing tRNS to alpha.

880

881

As of libpng version 1.2.46, not all possible expansions are supported.

882

883

In the following table, the 01 means grayscale with depth<8, 31 means

884

indexed with depth<8, other numerals represent the color type, "T" means

885

the tRNS chunk is present, A means an alpha channel is present, and O

886

means tRNS or alpha is present but all pixels in the image are opaque.

887

888

FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O

889

TO

890

01 -

891

31 -

892

0 1 -

893

0T -

894

0O -

895

2 GX -

896

2T -

897

2O -

898

3 1 -

899

3T -

900

3O -

901

4A T -

902

4O -

903

6A GX TX TX -

904

6O GX TX -

905

906

Within the matrix,

907

"-" means the transformation is not supported.

908

"X" means the transformation is obtained by png_set_expand().

909

"1" means the transformation is obtained by

910

png_set_expand_gray_1_2_4_to_8

911

"G" means the transformation is obtained by

912

png_set_gray_to_rgb().

913

"P" means the transformation is obtained by

914

png_set_expand_palette_to_rgb().

915

"T" means the transformation is obtained by

916

png_set_tRNS_to_alpha().

917

918

PNG can have files with 16 bits per channel. If you only can handle

919

8 bits per channel, this will strip the pixels down to 8 bit.

920

921

if (bit_depth == 16)

922

png_set_strip_16(png_ptr);

923

924

If, for some reason, you don't need the alpha channel on an image,

925

and you want to remove it rather than combining it with the background

926

(but the image author certainly had in mind that you *would* combine

927

it with the background, so that's what you should probably do):

928

929

if (color_type & PNG_COLOR_MASK_ALPHA)

930

png_set_strip_alpha(png_ptr);

931

932

In PNG files, the alpha channel in an image

933

is the level of opacity. If you need the alpha channel in an image to

934

be the level of transparency instead of opacity, you can invert the

935

alpha channel (or the tRNS chunk data) after it's read, so that 0 is

936

fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit

937

images) is fully transparent, with

938

939

png_set_invert_alpha(png_ptr);

940

941

The PNG format only supports pixels with postmultiplied alpha.

942

If you want to replace the pixels, after reading them, with pixels

943

that have premultiplied color samples, you can do this with

944

945

png_set_premultiply_alpha(png_ptr);

946

947

If you do this, any input with a tRNS chunk will be expanded to

948

have an alpha channel.

949

950

PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as

951

they can, resulting in, for example, 8 pixels per byte for 1 bit

952

files. This code expands to 1 pixel per byte without changing the

953

values of the pixels:

954

955

if (bit_depth < 8)

956

png_set_packing(png_ptr);

957

958

PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels

959

stored in a PNG image have been "scaled" or "shifted" up to the next

960

higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]

961

to 8 bits/sample in the range [0, 255]). However, it is also possible

962

to convert the PNG pixel data back to the original bit depth of the

963

image. This call reduces the pixels back down to the original bit depth:

964

965

png_color_8p sig_bit;

966

967

if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))

968

png_set_shift(png_ptr, sig_bit);

969

970

PNG files store 3-color pixels in red, green, blue order. This code

971

changes the storage of the pixels to blue, green, red:

972

973

if (color_type == PNG_COLOR_TYPE_RGB ||

974

color_type == PNG_COLOR_TYPE_RGB_ALPHA)

975

png_set_bgr(png_ptr);

976

977

PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them

978

into 4 or 8 bytes for windowing systems that need them in this format:

979

980

if (color_type == PNG_COLOR_TYPE_RGB)

981

png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);

982

983

where "filler" is the 8 or 16-bit number to fill with, and the location is

984

either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether

985

you want the filler before the RGB or after. This transformation

986

does not affect images that already have full alpha channels. To add an

987

opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which

988

will generate RGBA pixels.

989

990

Note that png_set_filler() does not change the color type. If you want

991

to do that, you can add a true alpha channel with

992

993

if (color_type == PNG_COLOR_TYPE_RGB ||

994

color_type == PNG_COLOR_TYPE_GRAY)

995

png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);

996

997

where "filler" contains the alpha value to assign to each pixel.

998

This function was added in libpng-1.2.7.

999

1000

If you are reading an image with an alpha channel, and you need the

1001

data as ARGB instead of the normal PNG format RGBA:

1002

1003

if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)

1004

png_set_swap_alpha(png_ptr);

1005

1006

For some uses, you may want a grayscale image to be represented as

1007

RGB. This code will do that conversion:

1008

1009

if (color_type == PNG_COLOR_TYPE_GRAY ||

1010

color_type == PNG_COLOR_TYPE_GRAY_ALPHA)

1011

png_set_gray_to_rgb(png_ptr);

1012

1013

Conversely, you can convert an RGB or RGBA image to grayscale or grayscale

1014

with alpha.

1015

1016

if (color_type == PNG_COLOR_TYPE_RGB ||

1017

color_type == PNG_COLOR_TYPE_RGB_ALPHA)

1018

png_set_rgb_to_gray_fixed(png_ptr, error_action,

1019

int red_weight, int green_weight);

1020

1021

error_action = 1: silently do the conversion

1022

error_action = 2: issue a warning if the original

1023

image has any pixel where

1024

red != green or red != blue

1025

error_action = 3: issue an error and abort the

1026

conversion if the original

1027

image has any pixel where

1028

red != green or red != blue

1029

1030

red_weight: weight of red component times 100000

1031

green_weight: weight of green component times 100000

1032

If either weight is negative, default

1033

weights (21268, 71514) are used.

1034

1035

If you have set error_action = 1 or 2, you can

1036

later check whether the image really was gray, after processing

1037

the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.

1038

It will return a png_byte that is zero if the image was gray or

1039

1 if there were any non-gray pixels. bKGD and sBIT data

1040

will be silently converted to grayscale, using the green channel

1041

data, regardless of the error_action setting.

1042

1043

With red_weight+green_weight<=100000,

1044

the normalized graylevel is computed:

1045

1046

int rw = red_weight * 65536;

1047

int gw = green_weight * 65536;

1048

int bw = 65536 - (rw + gw);

1049

gray = (rw*red + gw*green + bw*blue)/65536;

1050

1051

The default values approximate those recommended in the Charles

1052

Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>

1053

1054

1055

Y = 0.212671 * R + 0.715160 * G + 0.072169 * B

1056

1057

Libpng approximates this with

1058

1059

Y = 0.21268 * R + 0.7151 * G + 0.07217 * B

1060

1061

which can be expressed with integers as

1062

1063

Y = (6969 * R + 23434 * G + 2365 * B)/32768

1064

1065

The calculation is done in a linear colorspace, if the image gamma

1066

is known.

1067

1068

If you have a grayscale and you are using png_set_expand_depth(),

1069

png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to

1070

a higher bit-depth, you must either supply the background color as a gray

1071

value at the original file bit-depth (need_expand = 1) or else supply the

1072

background color as an RGB triplet at the final, expanded bit depth

1073

(need_expand = 0). Similarly, if you are reading a paletted image, you

1074

must either supply the background color as a palette index (need_expand = 1)

1075

or as an RGB triplet that may or may not be in the palette (need_expand = 0).

1076

1077

png_color_16 my_background;

1078

png_color_16p image_background;

1079

1080

if (png_get_bKGD(png_ptr, info_ptr, &image_background))

1081

png_set_background(png_ptr, image_background,

1082

PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);

1083

else

1084

png_set_background(png_ptr, &my_background,

1085

PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);

1086

1087

The png_set_background() function tells libpng to composite images

1088

with alpha or simple transparency against the supplied background

1089

color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),

1090

you may use this color, or supply another color more suitable for

1091

the current display (e.g., the background color from a web page). You

1092

need to tell libpng whether the color is in the gamma space of the

1093

display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file

1094

(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one

1095

that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't

1096

know why anyone would use this, but it's here).

1097

1098

To properly display PNG images on any kind of system, the application needs

1099

to know what the display gamma is. Ideally, the user will know this, and

1100

the application will allow them to set it. One method of allowing the user

1101

to set the display gamma separately for each system is to check for a

1102

SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be

1103

correctly set.

1104

1105

Note that display_gamma is the overall gamma correction required to produce

1106

pleasing results, which depends on the lighting conditions in the surrounding

1107

environment. In a dim or brightly lit room, no compensation other than

1108

the physical gamma exponent of the monitor is needed, while in a dark room

1109

a slightly smaller exponent is better.

1110

1111

double gamma, screen_gamma;

1112

1113

if (/* We have a user-defined screen

1114

gamma value */)

1115

{

1116

screen_gamma = user_defined_screen_gamma;

1117

}

1118

/* One way that applications can share the same

1119

screen gamma value */

1120

else if ((gamma_str = getenv("SCREEN_GAMMA"))

1121

!= NULL)

1122

{

1123

screen_gamma = (double)atof(gamma_str);

1124

}

1125

/* If we don't have another value */

1126

else

1127

{

1128

screen_gamma = 2.2; /* A good guess for a

1129

PC monitor in a bright office or a dim room */

1130

screen_gamma = 2.0; /* A good guess for a

1131

PC monitor in a dark room */

1132

screen_gamma = 1.7 or 1.0; /* A good

1133

guess for Mac systems */

1134

}

1135

1136

The png_set_gamma() function handles gamma transformations of the data.

1137

Pass both the file gamma and the current screen_gamma. If the file does

1138

not have a gamma value, you can pass one anyway if you have an idea what

1139

it is (usually 0.45455 is a good guess for GIF images on PCs). Note

1140

that file gammas are inverted from screen gammas. See the discussions

1141

on gamma in the PNG specification for an excellent description of what

1142

gamma is, and why all applications should support it. It is strongly

1143

recommended that PNG viewers support gamma correction.

1144

1145

if (png_get_gAMA(png_ptr, info_ptr, &gamma))

1146

png_set_gamma(png_ptr, screen_gamma, gamma);

1147

else

1148

png_set_gamma(png_ptr, screen_gamma, 0.45455);

1149

1150

If you need to reduce an RGB file to a paletted file, or if a paletted

1151

file has more entries then will fit on your screen, png_set_dither()

1152

will do that. Note that this is a simple match dither that merely

1153

finds the closest color available. This should work fairly well with

1154

optimized palettes, and fairly badly with linear color cubes. If you

1155

pass a palette that is larger then maximum_colors, the file will

1156

reduce the number of colors in the palette so it will fit into

1157

maximum_colors. If there is a histogram, it will use it to make

1158

more intelligent choices when reducing the palette. If there is no

1159

histogram, it may not do as good a job.

1160

1161

if (color_type & PNG_COLOR_MASK_COLOR)

1162

{

1163

if (png_get_valid(png_ptr, info_ptr,

1164

PNG_INFO_PLTE))

1165

{

1166

png_uint_16p histogram = NULL;

1167

1168

png_get_hIST(png_ptr, info_ptr,

1169

&histogram);

1170

png_set_dither(png_ptr, palette, num_palette,

1171

max_screen_colors, histogram, 1);

1172

}

1173

else

1174

{

1175

png_color std_color_cube[MAX_SCREEN_COLORS] =

1176

{ ... colors ... };

1177

1178

png_set_dither(png_ptr, std_color_cube,

1179

MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,

1180

NULL,0);

1181

}

1182

}

1183

1184

PNG files describe monochrome as black being zero and white being one.

1185

The following code will reverse this (make black be one and white be

1186

zero):

1187

1188

if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)

1189

png_set_invert_mono(png_ptr);

1190

1191

This function can also be used to invert grayscale and gray-alpha images:

1192

1193

if (color_type == PNG_COLOR_TYPE_GRAY ||

1194

color_type == PNG_COLOR_TYPE_GRAY_ALPHA)

1195

png_set_invert_mono(png_ptr);

1196

1197

PNG files store 16 bit pixels in network byte order (big-endian,

1198

ie. most significant bits first). This code changes the storage to the

1199

other way (little-endian, i.e. least significant bits first, the

1200

way PCs store them):

1201

1202

if (bit_depth == 16)

1203

png_set_swap(png_ptr);

1204

1205

If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you

1206

need to change the order the pixels are packed into bytes, you can use:

1207

1208

if (bit_depth < 8)

1209

png_set_packswap(png_ptr);

1210

1211

Finally, you can write your own transformation function if none of

1212

the existing ones meets your needs. This is done by setting a callback

1213

with

1214

1215

png_set_read_user_transform_fn(png_ptr,

1216

read_transform_fn);

1217

1218

You must supply the function

1219

1220

void read_transform_fn(png_ptr ptr, row_info_ptr

1221

row_info, png_bytep data)

1222

1223

See pngtest.c for a working example. Your function will be called

1224

after all of the other transformations have been processed.

1225

1226

You can also set up a pointer to a user structure for use by your

1227

callback function, and you can inform libpng that your transform

1228

function will change the number of channels or bit depth with the

1229

function

1230

1231

png_set_user_transform_info(png_ptr, user_ptr,

1232

user_depth, user_channels);

1233

1234

The user's application, not libpng, is responsible for allocating and

1235

freeing any memory required for the user structure.

1236

1237

You can retrieve the pointer via the function

1238

png_get_user_transform_ptr(). For example:

1239

1240

voidp read_user_transform_ptr =

1241

png_get_user_transform_ptr(png_ptr);

1242

1243

The last thing to handle is interlacing; this is covered in detail below,

1244

but you must call the function here if you want libpng to handle expansion

1245

of the interlaced image.

1246

1247

number_of_passes = png_set_interlace_handling(png_ptr);

1248

1249

After setting the transformations, libpng can update your png_info

1250

structure to reflect any transformations you've requested with this

1251

call. This is most useful to update the info structure's rowbytes

1252

field so you can use it to allocate your image memory. This function

1253

will also update your palette with the correct screen_gamma and

1254

background if these have been given with the calls above.

1255

1256

png_read_update_info(png_ptr, info_ptr);

1257

1258

After you call png_read_update_info(), you can allocate any

1259

memory you need to hold the image. The row data is simply

1260

raw byte data for all forms of images. As the actual allocation

1261

varies among applications, no example will be given. If you

1262

are allocating one large chunk, you will need to build an

1263

array of pointers to each row, as it will be needed for some

1264

of the functions below.

1265

1266

Reading image data

1267

1268

After you've allocated memory, you can read the image data.

1269

The simplest way to do this is in one function call. If you are

1270

allocating enough memory to hold the whole image, you can just

1271

call png_read_image() and libpng will read in all the image data

1272

and put it in the memory area supplied. You will need to pass in

1273

an array of pointers to each row.

1274

1275

This function automatically handles interlacing, so you don't need

1276

to call png_set_interlace_handling() or call this function multiple

1277

times, or any of that other stuff necessary with png_read_rows().

1278

1279

png_read_image(png_ptr, row_pointers);

1280

1281

where row_pointers is:

1282

1283

png_bytep row_pointers[height];

1284

1285

You can point to void or char or whatever you use for pixels.

1286

1287

If you don't want to read in the whole image at once, you can

1288

use png_read_rows() instead. If there is no interlacing (check

1289

interlace_type == PNG_INTERLACE_NONE), this is simple:

1290

1291

png_read_rows(png_ptr, row_pointers, NULL,

1292

number_of_rows);

1293

1294

where row_pointers is the same as in the png_read_image() call.

1295

1296

If you are doing this just one row at a time, you can do this with

1297

a single row_pointer instead of an array of row_pointers:

1298

1299

png_bytep row_pointer = row;

1300

png_read_row(png_ptr, row_pointer, NULL);

1301

1302

If the file is interlaced (interlace_type != 0 in the IHDR chunk), things

1303

get somewhat harder. The only current (PNG Specification version 1.2)

1304

interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)

1305

is a somewhat complicated 2D interlace scheme, known as Adam7, that

1306

breaks down an image into seven smaller images of varying size, based

1307

on an 8x8 grid.

1308

1309

libpng can fill out those images or it can give them to you "as is".

1310

If you want them filled out, there are two ways to do that. The one

1311

mentioned in the PNG specification is to expand each pixel to cover

1312

those pixels that have not been read yet (the "rectangle" method).

1313

This results in a blocky image for the first pass, which gradually

1314

smooths out as more pixels are read. The other method is the "sparkle"

1315

method, where pixels are drawn only in their final locations, with the

1316

rest of the image remaining whatever colors they were initialized to

1317

before the start of the read. The first method usually looks better,

1318

but tends to be slower, as there are more pixels to put in the rows.

1319

1320

If you don't want libpng to handle the interlacing details, just call

1321

png_read_rows() seven times to read in all seven images. Each of the

1322

images is a valid image by itself, or they can all be combined on an

1323

8x8 grid to form a single image (although if you intend to combine them

1324

you would be far better off using the libpng interlace handling).

1325

1326

The first pass will return an image 1/8 as wide as the entire image

1327

(every 8th column starting in column 0) and 1/8 as high as the original

1328

(every 8th row starting in row 0), the second will be 1/8 as wide

1329

(starting in column 4) and 1/8 as high (also starting in row 0). The

1330

third pass will be 1/4 as wide (every 4th pixel starting in column 0) and

1331

1/8 as high (every 8th row starting in row 4), and the fourth pass will

1332

be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,

1333

and every 4th row starting in row 0). The fifth pass will return an

1334

image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),

1335

while the sixth pass will be 1/2 as wide and 1/2 as high as the original

1336

(starting in column 1 and row 0). The seventh and final pass will be as

1337

wide as the original, and 1/2 as high, containing all of the odd

1338

numbered scanlines. Phew!

1339

1340

If you want libpng to expand the images, call this before calling

1341

png_start_read_image() or png_read_update_info():

1342

1343

if (interlace_type == PNG_INTERLACE_ADAM7)

1344

number_of_passes

1345

= png_set_interlace_handling(png_ptr);

1346

1347

This will return the number of passes needed. Currently, this

1348

is seven, but may change if another interlace type is added.

1349

This function can be called even if the file is not interlaced,

1350

where it will return one pass.

1351

1352

If you are not going to display the image after each pass, but are

1353

going to wait until the entire image is read in, use the sparkle

1354

effect. This effect is faster and the end result of either method

1355

is exactly the same. If you are planning on displaying the image

1356

after each pass, the "rectangle" effect is generally considered the

1357

better looking one.

1358

1359

If you only want the "sparkle" effect, just call png_read_rows() as

1360

normal, with the third parameter NULL. Make sure you make pass over

1361

the image number_of_passes times, and you don't change the data in the

1362

rows between calls. You can change the locations of the data, just

1363

not the data. Each pass only writes the pixels appropriate for that

1364

pass, and assumes the data from previous passes is still valid.

1365

1366

png_read_rows(png_ptr, row_pointers, NULL,

1367

number_of_rows);

1368

1369

If you only want the first effect (the rectangles), do the same as

1370

before except pass the row buffer in the third parameter, and leave

1371

the second parameter NULL.

1372

1373

png_read_rows(png_ptr, NULL, row_pointers,

1374

number_of_rows);

1375

1376

Finishing a sequential read

1377

1378

After you are finished reading the image through the

1379

low-level interface, you can finish reading the file. If you are

1380

interested in comments or time, which may be stored either before or

1381

after the image data, you should pass the separate png_info struct if

1382

you want to keep the comments from before and after the image

1383

separate. If you are not interested, you can pass NULL.

1384

1385

png_read_end(png_ptr, end_info);

1386

1387

When you are done, you can free all memory allocated by libpng like this:

1388

1389

png_destroy_read_struct(&png_ptr, &info_ptr,

1390

&end_info);

1391

1392

It is also possible to individually free the info_ptr members that

1393

point to libpng-allocated storage with the following function:

1394

1395

png_free_data(png_ptr, info_ptr, mask, seq)

1396

mask - identifies data to be freed, a mask

1397

containing the bitwise OR of one or

1398

more of

1399

PNG_FREE_PLTE, PNG_FREE_TRNS,

1400

PNG_FREE_HIST, PNG_FREE_ICCP,

1401

PNG_FREE_PCAL, PNG_FREE_ROWS,

1402

PNG_FREE_SCAL, PNG_FREE_SPLT,

1403

PNG_FREE_TEXT, PNG_FREE_UNKN,

1404

or simply PNG_FREE_ALL

1405

seq - sequence number of item to be freed

1406

(-1 for all items)

1407

1408

This function may be safely called when the relevant storage has

1409

already been freed, or has not yet been allocated, or was allocated

1410

by the user and not by libpng, and will in those cases do nothing.

1411

The "seq" parameter is ignored if only one item of the selected data

1412

type, such as PLTE, is allowed. If "seq" is not -1, and multiple items

1413

are allowed for the data type identified in the mask, such as text or

1414

sPLT, only the n'th item in the structure is freed, where n is "seq".

1415

1416

The default behavior is only to free data that was allocated internally

1417

by libpng. This can be changed, so that libpng will not free the data,

1418

or so that it will free data that was allocated by the user with png_malloc()

1419

or png_zalloc() and passed in via a png_set_*() function, with

1420

1421

png_data_freer(png_ptr, info_ptr, freer, mask)

1422

mask - which data elements are affected

1423

same choices as in png_free_data()

1424

freer - one of

1425

PNG_DESTROY_WILL_FREE_DATA

1426

PNG_SET_WILL_FREE_DATA

1427

PNG_USER_WILL_FREE_DATA

1428

1429

This function only affects data that has already been allocated.

1430

You can call this function after reading the PNG data but before calling

1431

any png_set_*() functions, to control whether the user or the png_set_*()

1432

function is responsible for freeing any existing data that might be present,

1433

and again after the png_set_*() functions to control whether the user

1434

or png_destroy_*() is supposed to free the data. When the user assumes

1435

responsibility for libpng-allocated data, the application must use

1436

png_free() to free it, and when the user transfers responsibility to libpng

1437

for data that the user has allocated, the user must have used png_malloc()

1438

or png_zalloc() to allocate it.

1439

1440

If you allocated your row_pointers in a single block, as suggested above in

1441

the description of the high level read interface, you must not transfer

1442

responsibility for freeing it to the png_set_rows or png_read_destroy function,

1443

because they would also try to free the individual row_pointers[i].

1444

1445

If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword

1446

separately, do not transfer responsibility for freeing text_ptr to libpng,

1447

because when libpng fills a png_text structure it combines these members with

1448

the key member, and png_free_data() will free only text_ptr.key. Similarly,

1449

if you transfer responsibility for free'ing text_ptr from libpng to your

1450

application, your application must not separately free those members.

1451

1452

The png_free_data() function will turn off the "valid" flag for anything

1453

it frees. If you need to turn the flag off for a chunk that was freed by

1454

your application instead of by libpng, you can use

1455

1456

png_set_invalid(png_ptr, info_ptr, mask);

1457

mask - identifies the chunks to be made invalid,

1458

containing the bitwise OR of one or

1459

more of

1460

PNG_INFO_gAMA, PNG_INFO_sBIT,

1461

PNG_INFO_cHRM, PNG_INFO_PLTE,

1462

PNG_INFO_tRNS, PNG_INFO_bKGD,

1463

PNG_INFO_hIST, PNG_INFO_pHYs,

1464

PNG_INFO_oFFs, PNG_INFO_tIME,

1465

PNG_INFO_pCAL, PNG_INFO_sRGB,

1466

PNG_INFO_iCCP, PNG_INFO_sPLT,

1467

PNG_INFO_sCAL, PNG_INFO_IDAT

1468

1469

For a more compact example of reading a PNG image, see the file example.c.

1470

1471

Reading PNG files progressively

1472

1473

The progressive reader is slightly different then the non-progressive

1474

reader. Instead of calling png_read_info(), png_read_rows(), and

1475

png_read_end(), you make one call to png_process_data(), which calls

1476

callbacks when it has the info, a row, or the end of the image. You

1477

set up these callbacks with png_set_progressive_read_fn(). You don't

1478

have to worry about the input/output functions of libpng, as you are

1479

giving the library the data directly in png_process_data(). I will

1480

assume that you have read the section on reading PNG files above,

1481

so I will only highlight the differences (although I will show

1482

all of the code).

1483

1484

png_structp png_ptr;

1485

png_infop info_ptr;

1486

1487

/* An example code fragment of how you would

1488

initialize the progressive reader in your

1489

application. */

1490

int

1491

initialize_png_reader()

1492

{

1493

png_ptr = png_create_read_struct

1494

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1495

user_error_fn, user_warning_fn);

1496

if (!png_ptr)

1497

return (ERROR);

1498

info_ptr = png_create_info_struct(png_ptr);

1499

if (!info_ptr)

1500

{

1501

png_destroy_read_struct(&png_ptr, (png_infopp)NULL,

1502

(png_infopp)NULL);

1503

return (ERROR);

1504

}

1505

1506

if (setjmp(png_jmpbuf(png_ptr)))

1507

{

1508

png_destroy_read_struct(&png_ptr, &info_ptr,

1509

(png_infopp)NULL);

1510

return (ERROR);

1511

}

1512

1513

/* This one's new. You can provide functions

1514

to be called when the header info is valid,

1515

when each row is completed, and when the image

1516

is finished. If you aren't using all functions,

1517

you can specify NULL parameters. Even when all

1518

three functions are NULL, you need to call

1519

png_set_progressive_read_fn(). You can use

1520

any struct as the user_ptr (cast to a void pointer

1521

for the function call), and retrieve the pointer

1522

from inside the callbacks using the function

1523

1524

png_get_progressive_ptr(png_ptr);

1525

1526

which will return a void pointer, which you have

1527

to cast appropriately.

1528

*/

1529

png_set_progressive_read_fn(png_ptr, (void *)user_ptr,

1530

info_callback, row_callback, end_callback);

1531

1532

return 0;

1533

}

1534

1535

/* A code fragment that you call as you receive blocks

1536

of data */

1537

int

1538

process_data(png_bytep buffer, png_uint_32 length)

1539

{

1540

if (setjmp(png_jmpbuf(png_ptr)))

1541

{

1542

png_destroy_read_struct(&png_ptr, &info_ptr,

1543

(png_infopp)NULL);

1544

return (ERROR);

1545

}

1546

1547

/* This one's new also. Simply give it a chunk

1548

of data from the file stream (in order, of

1549

course). On machines with segmented memory

1550

models machines, don't give it any more than

1551

64K. The library seems to run fine with sizes

1552

of 4K. Although you can give it much less if

1553

necessary (I assume you can give it chunks of

1554

1 byte, I haven't tried less then 256 bytes

1555

yet). When this function returns, you may

1556

want to display any rows that were generated

1557

in the row callback if you don't already do

1558

so there.

1559

*/

1560

png_process_data(png_ptr, info_ptr, buffer, length);

1561

return 0;

1562

}

1563

1564

/* This function is called (as set by

1565

png_set_progressive_read_fn() above) when enough data

1566

has been supplied so all of the header has been

1567

read.

1568

*/

1569

void

1570

info_callback(png_structp png_ptr, png_infop info)

1571

{

1572

/* Do any setup here, including setting any of

1573

the transformations mentioned in the Reading

1574

PNG files section. For now, you _must_ call

1575

either png_start_read_image() or

1576

png_read_update_info() after all the

1577

transformations are set (even if you don't set

1578

any). You may start getting rows before

1579

png_process_data() returns, so this is your

1580

last chance to prepare for that.

1581

*/

1582

}

1583

1584

/* This function is called when each row of image

1585

data is complete */

1586

void

1587

row_callback(png_structp png_ptr, png_bytep new_row,

1588

png_uint_32 row_num, int pass)

1589

{

1590

/* If the image is interlaced, and you turned

1591

on the interlace handler, this function will

1592

be called for every row in every pass. Some

1593

of these rows will not be changed from the

1594

previous pass. When the row is not changed,

1595

the new_row variable will be NULL. The rows

1596

and passes are called in order, so you don't

1597

really need the row_num and pass, but I'm

1598

supplying them because it may make your life

1599

easier.

1600

1601

For the non-NULL rows of interlaced images,

1602

you must call png_progressive_combine_row()

1603

passing in the row and the old row. You can

1604

call this function for NULL rows (it will just

1605

return) and for non-interlaced images (it just

1606

does the memcpy for you) if it will make the

1607

code easier. Thus, you can just do this for

1608

all cases:

1609

*/

1610

1611

png_progressive_combine_row(png_ptr, old_row,

1612

new_row);

1613

1614

/* where old_row is what was displayed for

1615

previously for the row. Note that the first

1616

pass (pass == 0, really) will completely cover

1617

the old row, so the rows do not have to be

1618

initialized. After the first pass (and only

1619

for interlaced images), you will have to pass

1620

the current row, and the function will combine

1621

the old row and the new row.

1622

*/

1623

}

1624

1625

void

1626

end_callback(png_structp png_ptr, png_infop info)

1627

{

1628

/* This function is called after the whole image

1629

has been read, including any chunks after the

1630

image (up to and including the IEND). You

1631

will usually have the same info chunk as you

1632

had in the header, although some data may have

1633

been added to the comments and time fields.

1634

1635

Most people won't do much here, perhaps setting

1636

a flag that marks the image as finished.

1637

*/

1638

}

1639

1640

1641

1642

IV. Writing

1643

1644

Much of this is very similar to reading. However, everything of

1645

importance is repeated here, so you won't have to constantly look

1646

back up in the reading section to understand writing.

1647

1648

Setup

1649

1650

You will want to do the I/O initialization before you get into libpng,

1651

so if it doesn't work, you don't have anything to undo. If you are not

1652

using the standard I/O functions, you will need to replace them with

1653

custom writing functions. See the discussion under Customizing libpng.

1654

1655

FILE *fp = fopen(file_name, "wb");

1656

if (!fp)

1657

{

1658

return (ERROR);

1659

}

1660

1661

Next, png_struct and png_info need to be allocated and initialized.

1662

As these can be both relatively large, you may not want to store these

1663

on the stack, unless you have stack space to spare. Of course, you

1664

will want to check if they return NULL. If you are also reading,

1665

you won't want to name your read structure and your write structure

1666

both "png_ptr"; you can call them anything you like, such as

1667

"read_ptr" and "write_ptr". Look at pngtest.c, for example.

1668

1669

png_structp png_ptr = png_create_write_struct

1670

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1671

user_error_fn, user_warning_fn);

1672

if (!png_ptr)

1673

return (ERROR);

1674

1675

png_infop info_ptr = png_create_info_struct(png_ptr);

1676

if (!info_ptr)

1677

{

1678

png_destroy_write_struct(&png_ptr,

1679

(png_infopp)NULL);

1680

return (ERROR);

1681

}

1682

1683

If you want to use your own memory allocation routines,

1684

define PNG_USER_MEM_SUPPORTED and use

1685

png_create_write_struct_2() instead of png_create_write_struct():

1686

1687

png_structp png_ptr = png_create_write_struct_2

1688

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1689

user_error_fn, user_warning_fn, (png_voidp)

1690

user_mem_ptr, user_malloc_fn, user_free_fn);

1691

1692

After you have these structures, you will need to set up the

1693

error handling. When libpng encounters an error, it expects to

1694

longjmp() back to your routine. Therefore, you will need to call

1695

setjmp() and pass the png_jmpbuf(png_ptr). If you

1696

write the file from different routines, you will need to update

1697

the png_jmpbuf(png_ptr) every time you enter a new routine that will

1698

call a png_*() function. See your documentation of setjmp/longjmp

1699

for your compiler for more information on setjmp/longjmp. See

1700

the discussion on libpng error handling in the Customizing Libpng

1701

section below for more information on the libpng error handling.

1702

1703

if (setjmp(png_jmpbuf(png_ptr)))

1704

{

1705

png_destroy_write_struct(&png_ptr, &info_ptr);

1706

fclose(fp);

1707

return (ERROR);

1708

}

1709

...

1710

return;

1711

1712

If you would rather avoid the complexity of setjmp/longjmp issues,

1713

you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case

1714

errors will result in a call to PNG_ABORT() which defaults to abort().

1715

1716

Now you need to set up the output code. The default for libpng is to

1717

use the C function fwrite(). If you use this, you will need to pass a

1718

valid FILE * in the function png_init_io(). Be sure that the file is

1719

opened in binary mode. Again, if you wish to handle writing data in

1720

another way, see the discussion on libpng I/O handling in the Customizing

1721

Libpng section below.

1722

1723

png_init_io(png_ptr, fp);

1724

1725

If you are embedding your PNG into a datastream such as MNG, and don't

1726

want libpng to write the 8-byte signature, or if you have already

1727

written the signature in your application, use

1728

1729

png_set_sig_bytes(png_ptr, 8);

1730

1731

to inform libpng that it should not write a signature.

1732

1733

Write callbacks

1734

1735

At this point, you can set up a callback function that will be

1736

called after each row has been written, which you can use to control

1737

a progress meter or the like. It's demonstrated in pngtest.c.

1738

You must supply a function

1739

1740

void write_row_callback(png_ptr, png_uint_32 row,

1741

int pass);

1742

{

1743

/* put your code here */

1744

}

1745

1746

(You can give it another name that you like instead of "write_row_callback")

1747

1748

To inform libpng about your function, use

1749

1750

png_set_write_status_fn(png_ptr, write_row_callback);

1751

1752

You now have the option of modifying how the compression library will

1753

run. The following functions are mainly for testing, but may be useful

1754

in some cases, like if you need to write PNG files extremely fast and

1755

are willing to give up some compression, or if you want to get the

1756

maximum possible compression at the expense of slower writing. If you

1757

have no special needs in this area, let the library do what it wants by

1758

not calling this function at all, as it has been tuned to deliver a good

1759

speed/compression ratio. The second parameter to png_set_filter() is

1760

the filter method, for which the only valid values are 0 (as of the

1761

July 1999 PNG specification, version 1.2) or 64 (if you are writing

1762

a PNG datastream that is to be embedded in a MNG datastream). The third

1763

parameter is a flag that indicates which filter type(s) are to be tested

1764

for each scanline. See the PNG specification for details on the specific

1765

filter types.

1766

1767

1768

/* turn on or off filtering, and/or choose

1769

specific filters. You can use either a single

1770

PNG_FILTER_VALUE_NAME or the bitwise OR of one

1771

or more PNG_FILTER_NAME masks. */

1772

png_set_filter(png_ptr, 0,

1773

PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |

1774

PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |

1775

PNG_FILTER_UP | PNG_FILTER_VALUE_UP |

1776

PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |

1777

PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|

1778

PNG_ALL_FILTERS);

1779

1780

If an application

1781

wants to start and stop using particular filters during compression,

1782

it should start out with all of the filters (to ensure that the previous

1783

row of pixels will be stored in case it's needed later), and then add

1784

and remove them after the start of compression.

1785

1786

If you are writing a PNG datastream that is to be embedded in a MNG

1787

datastream, the second parameter can be either 0 or 64.

1788

1789

The png_set_compression_*() functions interface to the zlib compression

1790

library, and should mostly be ignored unless you really know what you are

1791

doing. The only generally useful call is png_set_compression_level()

1792

which changes how much time zlib spends on trying to compress the image

1793

data. See the Compression Library (zlib.h and algorithm.txt, distributed

1794

with zlib) for details on the compression levels.

1795

1796

/* set the zlib compression level */

1797

png_set_compression_level(png_ptr,

1798

Z_BEST_COMPRESSION);

1799

1800

/* set other zlib parameters */

1801

png_set_compression_mem_level(png_ptr, 8);

1802

png_set_compression_strategy(png_ptr,

1803

Z_DEFAULT_STRATEGY);

1804

png_set_compression_window_bits(png_ptr, 15);

1805

png_set_compression_method(png_ptr, 8);

1806

png_set_compression_buffer_size(png_ptr, 8192)

1807

1808

extern PNG_EXPORT(void,png_set_zbuf_size)

1809

1810

Setting the contents of info for output

1811

1812

You now need to fill in the png_info structure with all the data you

1813

wish to write before the actual image. Note that the only thing you

1814

are allowed to write after the image is the text chunks and the time

1815

chunk (as of PNG Specification 1.2, anyway). See png_write_end() and

1816

the latest PNG specification for more information on that. If you

1817

wish to write them before the image, fill them in now, and flag that

1818

data as being valid. If you want to wait until after the data, don't

1819

fill them until png_write_end(). For all the fields in png_info and

1820

their data types, see png.h. For explanations of what the fields

1821

contain, see the PNG specification.

1822

1823

Some of the more important parts of the png_info are:

1824

1825

png_set_IHDR(png_ptr, info_ptr, width, height,

1826

bit_depth, color_type, interlace_type,

1827

compression_type, filter_method)

1828

width - holds the width of the image

1829

in pixels (up to 2^31).

1830

height - holds the height of the image

1831

in pixels (up to 2^31).

1832

bit_depth - holds the bit depth of one of the

1833

image channels.

1834

(valid values are 1, 2, 4, 8, 16

1835

and depend also on the

1836

color_type. See also significant

1837

bits (sBIT) below).

1838

color_type - describes which color/alpha

1839

channels are present.

1840

PNG_COLOR_TYPE_GRAY

1841

(bit depths 1, 2, 4, 8, 16)

1842

PNG_COLOR_TYPE_GRAY_ALPHA

1843

(bit depths 8, 16)

1844

PNG_COLOR_TYPE_PALETTE

1845

(bit depths 1, 2, 4, 8)

1846

PNG_COLOR_TYPE_RGB

1847

(bit_depths 8, 16)

1848

PNG_COLOR_TYPE_RGB_ALPHA

1849

(bit_depths 8, 16)

1850

1851

PNG_COLOR_MASK_PALETTE

1852

PNG_COLOR_MASK_COLOR

1853

PNG_COLOR_MASK_ALPHA

1854

1855

interlace_type - PNG_INTERLACE_NONE or

1856

PNG_INTERLACE_ADAM7

1857

compression_type - (must be

1858

PNG_COMPRESSION_TYPE_DEFAULT)

1859

filter_method - (must be PNG_FILTER_TYPE_DEFAULT

1860

or, if you are writing a PNG to

1861

be embedded in a MNG datastream,

1862

can also be

1863

PNG_INTRAPIXEL_DIFFERENCING)

1864

1865

If you call png_set_IHDR(), the call must appear before any of the

1866

other png_set_*() functions, because they might require access to some of

1867

the IHDR settings. The remaining png_set_*() functions can be called

1868

in any order.

1869

1870

If you wish, you can reset the compression_type, interlace_type, or

1871

filter_method later by calling png_set_IHDR() again; if you do this, the

1872

width, height, bit_depth, and color_type must be the same in each call.

1873

1874

png_set_PLTE(png_ptr, info_ptr, palette,

1875

num_palette);

1876

palette - the palette for the file

1877

(array of png_color)

1878

num_palette - number of entries in the palette

1879

1880

png_set_gAMA(png_ptr, info_ptr, gamma);

1881

gamma - the gamma the image was created

1882

at (PNG_INFO_gAMA)

1883

1884

png_set_sRGB(png_ptr, info_ptr, srgb_intent);

1885

srgb_intent - the rendering intent

1886

(PNG_INFO_sRGB) The presence of

1887

the sRGB chunk means that the pixel

1888

data is in the sRGB color space.

1889

This chunk also implies specific

1890

values of gAMA and cHRM. Rendering

1891

intent is the CSS-1 property that

1892

has been defined by the International

1893

Color Consortium

1894

(http://www.color.org).

1895

It can be one of

1896

PNG_sRGB_INTENT_SATURATION,

1897

PNG_sRGB_INTENT_PERCEPTUAL,

1898

PNG_sRGB_INTENT_ABSOLUTE, or

1899

PNG_sRGB_INTENT_RELATIVE.

1900

1901

1902

png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,

1903

srgb_intent);

1904

srgb_intent - the rendering intent

1905

(PNG_INFO_sRGB) The presence of the

1906

sRGB chunk means that the pixel

1907

data is in the sRGB color space.

1908

This function also causes gAMA and

1909

cHRM chunks with the specific values

1910

that are consistent with sRGB to be

1911

written.

1912

1913

png_set_iCCP(png_ptr, info_ptr, name, compression_type,

1914

profile, proflen);

1915

name - The profile name.

1916

compression - The compression type; always

1917

PNG_COMPRESSION_TYPE_BASE for PNG 1.0.

1918

You may give NULL to this argument to

1919

ignore it.

1920

profile - International Color Consortium color

1921

profile data. May contain NULs.

1922

proflen - length of profile data in bytes.

1923

1924

png_set_sBIT(png_ptr, info_ptr, sig_bit);

1925

sig_bit - the number of significant bits for

1926

(PNG_INFO_sBIT) each of the gray, red,

1927

green, and blue channels, whichever are

1928

appropriate for the given color type

1929

(png_color_16)

1930

1931

png_set_tRNS(png_ptr, info_ptr, trans, num_trans,

1932

trans_values);

1933

trans - array of transparent

1934

entries for palette (PNG_INFO_tRNS)

1935

trans_values - graylevel or color sample values

1936

(in order red, green, blue) of the

1937

single transparent color for

1938

non-paletted images (PNG_INFO_tRNS)

1939

num_trans - number of transparent entries

1940

(PNG_INFO_tRNS)

1941

1942

png_set_hIST(png_ptr, info_ptr, hist);

1943

(PNG_INFO_hIST)

1944

hist - histogram of palette (array of

1945

png_uint_16)

1946

1947

png_set_tIME(png_ptr, info_ptr, mod_time);

1948

mod_time - time image was last modified

1949

(PNG_VALID_tIME)

1950

1951

png_set_bKGD(png_ptr, info_ptr, background);

1952

background - background color (PNG_VALID_bKGD)

1953

1954

png_set_text(png_ptr, info_ptr, text_ptr, num_text);

1955

text_ptr - array of png_text holding image

1956

comments

1957

text_ptr[i].compression - type of compression used

1958

on "text" PNG_TEXT_COMPRESSION_NONE

1959

PNG_TEXT_COMPRESSION_zTXt

1960

PNG_ITXT_COMPRESSION_NONE

1961

PNG_ITXT_COMPRESSION_zTXt

1962

text_ptr[i].key - keyword for comment. Must contain

1963

1-79 characters.

1964

text_ptr[i].text - text comments for current

1965

keyword. Can be NULL or empty.

1966

text_ptr[i].text_length - length of text string,

1967

after decompression, 0 for iTXt

1968

text_ptr[i].itxt_length - length of itxt string,

1969

after decompression, 0 for tEXt/zTXt

1970

text_ptr[i].lang - language of comment (NULL or

1971

empty for unknown).

1972

text_ptr[i].translated_keyword - keyword in UTF-8 (NULL

1973

or empty for unknown).

1974

Note that the itxt_length, lang, and lang_key

1975

members of the text_ptr structure only exist

1976

when the library is built with iTXt chunk support.

1977

1978

num_text - number of comments

1979

1980

png_set_sPLT(png_ptr, info_ptr, &palette_ptr,

1981

num_spalettes);

1982

palette_ptr - array of png_sPLT_struct structures

1983

to be added to the list of palettes

1984

in the info structure.

1985

num_spalettes - number of palette structures to be

1986

added.

1987

1988

png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,

1989

unit_type);

1990

offset_x - positive offset from the left

1991

edge of the screen

1992

offset_y - positive offset from the top

1993

edge of the screen

1994

unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER

1995

1996

png_set_pHYs(png_ptr, info_ptr, res_x, res_y,

1997

unit_type);

1998

res_x - pixels/unit physical resolution

1999

in x direction

2000

res_y - pixels/unit physical resolution

2001

in y direction

2002

unit_type - PNG_RESOLUTION_UNKNOWN,

2003

PNG_RESOLUTION_METER

2004

2005

png_set_sCAL(png_ptr, info_ptr, unit, width, height)

2006

unit - physical scale units (an integer)

2007

width - width of a pixel in physical scale units

2008

height - height of a pixel in physical scale units

2009

(width and height are doubles)

2010

2011

png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)

2012

unit - physical scale units (an integer)

2013

width - width of a pixel in physical scale units

2014

height - height of a pixel in physical scale units

2015

(width and height are strings like "2.54")

2016

2017

png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,

2018

num_unknowns)

2019

unknowns - array of png_unknown_chunk

2020

structures holding unknown chunks

2021

unknowns[i].name - name of unknown chunk

2022

unknowns[i].data - data of unknown chunk

2023

unknowns[i].size - size of unknown chunk's data

2024

unknowns[i].location - position to write chunk in file

2025

0: do not write chunk

2026

PNG_HAVE_IHDR: before PLTE

2027

PNG_HAVE_PLTE: before IDAT

2028

PNG_AFTER_IDAT: after IDAT

2029

2030

The "location" member is set automatically according to

2031

what part of the output file has already been written.

2032

You can change its value after calling png_set_unknown_chunks()

2033

as demonstrated in pngtest.c. Within each of the "locations",

2034

the chunks are sequenced according to their position in the

2035

structure (that is, the value of "i", which is the order in which

2036

the chunk was either read from the input file or defined with

2037

png_set_unknown_chunks).

2038

2039

A quick word about text and num_text. text is an array of png_text

2040

structures. num_text is the number of valid structures in the array.

2041

Each png_text structure holds a language code, a keyword, a text value,

2042

and a compression type.

2043

2044

The compression types have the same valid numbers as the compression

2045

types of the image data. Currently, the only valid number is zero.

2046

However, you can store text either compressed or uncompressed, unlike

2047

images, which always have to be compressed. So if you don't want the

2048

text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.

2049

Because tEXt and zTXt chunks don't have a language field, if you

2050

specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt

2051

any language code or translated keyword will not be written out.

2052

2053

Until text gets around 1000 bytes, it is not worth compressing it.

2054

After the text has been written out to the file, the compression type

2055

is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,

2056

so that it isn't written out again at the end (in case you are calling

2057

png_write_end() with the same struct.

2058

2059

The keywords that are given in the PNG Specification are:

2060

2061

Title Short (one line) title or

2062

caption for image

2063

Author Name of image's creator

2064

Description Description of image (possibly long)

2065

Copyright Copyright notice

2066

Creation Time Time of original image creation

2067

(usually RFC 1123 format, see below)

2068

Software Software used to create the image

2069

Disclaimer Legal disclaimer

2070

Warning Warning of nature of content

2071

Source Device used to create the image

2072

Comment Miscellaneous comment; conversion

2073

from other image format

2074

2075

The keyword-text pairs work like this. Keywords should be short

2076

simple descriptions of what the comment is about. Some typical

2077

keywords are found in the PNG specification, as is some recommendations

2078

on keywords. You can repeat keywords in a file. You can even write

2079

some text before the image and some after. For example, you may want

2080

to put a description of the image before the image, but leave the

2081

disclaimer until after, so viewers working over modem connections

2082

don't have to wait for the disclaimer to go over the modem before

2083

they start seeing the image. Finally, keywords should be full

2084

words, not abbreviations. Keywords and text are in the ISO 8859-1

2085

(Latin-1) character set (a superset of regular ASCII) and can not

2086

contain NUL characters, and should not contain control or other

2087

unprintable characters. To make the comments widely readable, stick

2088

with basic ASCII, and avoid machine specific character set extensions

2089

like the IBM-PC character set. The keyword must be present, but

2090

you can leave off the text string on non-compressed pairs.

2091

Compressed pairs must have a text string, as only the text string

2092

is compressed anyway, so the compression would be meaningless.

2093

2094

PNG supports modification time via the png_time structure. Two

2095

conversion routines are provided, png_convert_from_time_t() for

2096

time_t and png_convert_from_struct_tm() for struct tm. The

2097

time_t routine uses gmtime(). You don't have to use either of

2098

these, but if you wish to fill in the png_time structure directly,

2099

you should provide the time in universal time (GMT) if possible

2100

instead of your local time. Note that the year number is the full

2101

year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and

2102

that months start with 1.

2103

2104

If you want to store the time of the original image creation, you should

2105

use a plain tEXt chunk with the "Creation Time" keyword. This is

2106

necessary because the "creation time" of a PNG image is somewhat vague,

2107

depending on whether you mean the PNG file, the time the image was

2108

created in a non-PNG format, a still photo from which the image was

2109

scanned, or possibly the subject matter itself. In order to facilitate

2110

machine-readable dates, it is recommended that the "Creation Time"

2111

tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),

2112

although this isn't a requirement. Unlike the tIME chunk, the

2113

"Creation Time" tEXt chunk is not expected to be automatically changed

2114

by the software. To facilitate the use of RFC 1123 dates, a function

2115

png_convert_to_rfc1123(png_timep) is provided to convert from PNG

2116

time to an RFC 1123 format string.

2117

2118

Writing unknown chunks

2119

2120

You can use the png_set_unknown_chunks function to queue up chunks

2121

for writing. You give it a chunk name, raw data, and a size; that's

2122

all there is to it. The chunks will be written by the next following

2123

png_write_info_before_PLTE, png_write_info, or png_write_end function.

2124

Any chunks previously read into the info structure's unknown-chunk

2125

list will also be written out in a sequence that satisfies the PNG

2126

specification's ordering rules.

2127

2128

The high-level write interface

2129

2130

At this point there are two ways to proceed; through the high-level

2131

write interface, or through a sequence of low-level write operations.

2132

You can use the high-level interface if your image data is present

2133

in the info structure. All defined output

2134

transformations are permitted, enabled by the following masks.

2135

2136

PNG_TRANSFORM_IDENTITY No transformation

2137

PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples

2138

PNG_TRANSFORM_PACKSWAP Change order of packed

2139

pixels to LSB first

2140

PNG_TRANSFORM_INVERT_MONO Invert monochrome images

2141

PNG_TRANSFORM_SHIFT Normalize pixels to the

2142

sBIT depth

2143

PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA

2144

to BGRA

2145

PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA

2146

to AG

2147

PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity

2148

to transparency

2149

PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples

2150

PNG_TRANSFORM_STRIP_FILLER Strip out filler

2151

bytes (deprecated).

2152

PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading

2153

filler bytes

2154

PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing

2155

filler bytes

2156

2157

If you have valid image data in the info structure (you can use

2158

png_set_rows() to put image data in the info structure), simply do this:

2159

2160

png_write_png(png_ptr, info_ptr, png_transforms, NULL)

2161

2162

where png_transforms is an integer containing the bitwise OR of some set of

2163

transformation flags. This call is equivalent to png_write_info(),

2164

followed the set of transformations indicated by the transform mask,

2165

then png_write_image(), and finally png_write_end().

2166

2167

(The final parameter of this call is not yet used. Someday it might point

2168

to transformation parameters required by some future output transform.)

2169

2170

You must use png_transforms and not call any png_set_transform() functions

2171

when you use png_write_png().

2172

2173

The low-level write interface

2174

2175

If you are going the low-level route instead, you are now ready to

2176

write all the file information up to the actual image data. You do

2177

this with a call to png_write_info().

2178

2179

png_write_info(png_ptr, info_ptr);

2180

2181

Note that there is one transformation you may need to do before

2182

png_write_info(). In PNG files, the alpha channel in an image is the

2183

level of opacity. If your data is supplied as a level of transparency,

2184

you can invert the alpha channel before you write it, so that 0 is

2185

fully transparent and 255 (in 8-bit or paletted images) or 65535

2186

(in 16-bit images) is fully opaque, with

2187

2188

png_set_invert_alpha(png_ptr);

2189

2190

This must appear before png_write_info() instead of later with the

2191

other transformations because in the case of paletted images the tRNS

2192

chunk data has to be inverted before the tRNS chunk is written. If

2193

your image is not a paletted image, the tRNS data (which in such cases

2194

represents a single color to be rendered as transparent) won't need to

2195

be changed, and you can safely do this transformation after your

2196

png_write_info() call.

2197

2198

If you need to write a private chunk that you want to appear before

2199

the PLTE chunk when PLTE is present, you can write the PNG info in

2200

two steps, and insert code to write your own chunk between them:

2201

2202

png_write_info_before_PLTE(png_ptr, info_ptr);

2203

png_set_unknown_chunks(png_ptr, info_ptr, ...);

2204

png_write_info(png_ptr, info_ptr);

2205

2206

After you've written the file information, you can set up the library

2207

to handle any special transformations of the image data. The various

2208

ways to transform the data will be described in the order that they

2209

should occur. This is important, as some of these change the color

2210

type and/or bit depth of the data, and some others only work on

2211

certain color types and bit depths. Even though each transformation

2212

checks to see if it has data that it can do something with, you should

2213

make sure to only enable a transformation if it will be valid for the

2214

data. For example, don't swap red and blue on grayscale data.

2215

2216

PNG files store RGB pixels packed into 3 or 6 bytes. This code tells

2217

the library to strip input data that has 4 or 8 bytes per pixel down

2218

to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2

2219

bytes per pixel).

2220

2221

png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);

2222

2223

where the 0 is unused, and the location is either PNG_FILLER_BEFORE or

2224

PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel

2225

is stored XRGB or RGBX.

2226

2227

PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as

2228

they can, resulting in, for example, 8 pixels per byte for 1 bit files.

2229

If the data is supplied at 1 pixel per byte, use this code, which will

2230

correctly pack the pixels into a single byte:

2231

2232

png_set_packing(png_ptr);

2233

2234

PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your

2235

data is of another bit depth, you can write an sBIT chunk into the

2236

file so that decoders can recover the original data if desired.

2237

2238

/* Set the true bit depth of the image data */

2239

if (color_type & PNG_COLOR_MASK_COLOR)

2240

{

2241

sig_bit.red = true_bit_depth;

2242

sig_bit.green = true_bit_depth;

2243

sig_bit.blue = true_bit_depth;

2244

}

2245

else

2246

{

2247

sig_bit.gray = true_bit_depth;

2248

}

2249

if (color_type & PNG_COLOR_MASK_ALPHA)

2250

{

2251

sig_bit.alpha = true_bit_depth;

2252

}

2253

2254

png_set_sBIT(png_ptr, info_ptr, &sig_bit);

2255

2256

If the data is stored in the row buffer in a bit depth other than

2257

one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),

2258

this will scale the values to appear to be the correct bit depth as

2259

is required by PNG.

2260

2261

png_set_shift(png_ptr, &sig_bit);

2262

2263

PNG files store 16 bit pixels in network byte order (big-endian,

2264

ie. most significant bits first). This code would be used if they are

2265

supplied the other way (little-endian, i.e. least significant bits

2266

first, the way PCs store them):

2267

2268

if (bit_depth > 8)

2269

png_set_swap(png_ptr);

2270

2271

If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you

2272

need to change the order the pixels are packed into bytes, you can use:

2273

2274

if (bit_depth < 8)

2275

png_set_packswap(png_ptr);

2276

2277

PNG files store 3 color pixels in red, green, blue order. This code

2278

would be used if they are supplied as blue, green, red:

2279

2280

png_set_bgr(png_ptr);

2281

2282

PNG files describe monochrome as black being zero and white being

2283

one. This code would be used if the pixels are supplied with this reversed

2284

(black being one and white being zero):

2285

2286

png_set_invert_mono(png_ptr);

2287

2288

Finally, you can write your own transformation function if none of

2289

the existing ones meets your needs. This is done by setting a callback

2290

with

2291

2292

png_set_write_user_transform_fn(png_ptr,

2293

write_transform_fn);

2294

2295

You must supply the function

2296

2297

void write_transform_fn(png_ptr ptr, row_info_ptr

2298

row_info, png_bytep data)

2299

2300

See pngtest.c for a working example. Your function will be called

2301

before any of the other transformations are processed.

2302

2303

You can also set up a pointer to a user structure for use by your

2304

callback function.

2305

2306

png_set_user_transform_info(png_ptr, user_ptr, 0, 0);

2307

2308

The user_channels and user_depth parameters of this function are ignored

2309

when writing; you can set them to zero as shown.

2310

2311

You can retrieve the pointer via the function png_get_user_transform_ptr().

2312

For example:

2313

2314

voidp write_user_transform_ptr =

2315

png_get_user_transform_ptr(png_ptr);

2316

2317

It is possible to have libpng flush any pending output, either manually,

2318

or automatically after a certain number of lines have been written. To

2319

flush the output stream a single time call:

2320

2321

png_write_flush(png_ptr);

2322

2323

and to have libpng flush the output stream periodically after a certain

2324

number of scanlines have been written, call:

2325

2326

png_set_flush(png_ptr, nrows);

2327

2328

Note that the distance between rows is from the last time png_write_flush()

2329

was called, or the first row of the image if it has never been called.

2330

So if you write 50 lines, and then png_set_flush 25, it will flush the

2331

output on the next scanline, and every 25 lines thereafter, unless

2332

png_write_flush() is called before 25 more lines have been written.

2333

If nrows is too small (less than about 10 lines for a 640 pixel wide

2334

RGB image) the image compression may decrease noticeably (although this

2335

may be acceptable for real-time applications). Infrequent flushing will

2336

only degrade the compression performance by a few percent over images

2337

that do not use flushing.

2338

2339

Writing the image data

2340

2341

That's it for the transformations. Now you can write the image data.

2342

The simplest way to do this is in one function call. If you have the

2343

whole image in memory, you can just call png_write_image() and libpng

2344

will write the image. You will need to pass in an array of pointers to

2345

each row. This function automatically handles interlacing, so you don't

2346

need to call png_set_interlace_handling() or call this function multiple

2347

times, or any of that other stuff necessary with png_write_rows().

2348

2349

png_write_image(png_ptr, row_pointers);

2350

2351

where row_pointers is:

2352

2353

png_byte *row_pointers[height];

2354

2355

You can point to void or char or whatever you use for pixels.

2356

2357

If you don't want to write the whole image at once, you can

2358

use png_write_rows() instead. If the file is not interlaced,

2359

this is simple:

2360

2361

png_write_rows(png_ptr, row_pointers,

2362

number_of_rows);

2363

2364

row_pointers is the same as in the png_write_image() call.

2365

2366

If you are just writing one row at a time, you can do this with

2367

a single row_pointer instead of an array of row_pointers:

2368

2369

png_bytep row_pointer = row;

2370

2371

png_write_row(png_ptr, row_pointer);

2372

2373

When the file is interlaced, things can get a good deal more complicated.

2374

The only currently (as of the PNG Specification version 1.2, dated July

2375

1999) defined interlacing scheme for PNG files is the "Adam7" interlace

2376

scheme, that breaks down an image into seven smaller images of varying

2377

size. libpng will build these images for you, or you can do them

2378

yourself. If you want to build them yourself, see the PNG specification

2379

for details of which pixels to write when.

2380

2381

If you don't want libpng to handle the interlacing details, just

2382

use png_set_interlace_handling() and call png_write_rows() the

2383

correct number of times to write all seven sub-images.

2384

2385

If you want libpng to build the sub-images, call this before you start

2386

writing any rows:

2387

2388

number_of_passes =

2389

png_set_interlace_handling(png_ptr);

2390

2391

This will return the number of passes needed. Currently, this is seven,

2392

but may change if another interlace type is added.

2393

2394

Then write the complete image number_of_passes times.

2395

2396

png_write_rows(png_ptr, row_pointers,

2397

number_of_rows);

2398

2399

As some of these rows are not used, and thus return immediately, you may

2400

want to read about interlacing in the PNG specification, and only update

2401

the rows that are actually used.

2402

2403

Finishing a sequential write

2404

2405

After you are finished writing the image, you should finish writing

2406

the file. If you are interested in writing comments or time, you should

2407

pass an appropriately filled png_info pointer. If you are not interested,

2408

you can pass NULL.

2409

2410

png_write_end(png_ptr, info_ptr);

2411

2412

When you are done, you can free all memory used by libpng like this:

2413

2414

png_destroy_write_struct(&png_ptr, &info_ptr);

2415

2416

It is also possible to individually free the info_ptr members that

2417

point to libpng-allocated storage with the following function:

2418

2419

png_free_data(png_ptr, info_ptr, mask, seq)

2420

mask - identifies data to be freed, a mask

2421

containing the bitwise OR of one or

2422

more of

2423

PNG_FREE_PLTE, PNG_FREE_TRNS,

2424

PNG_FREE_HIST, PNG_FREE_ICCP,

2425

PNG_FREE_PCAL, PNG_FREE_ROWS,

2426

PNG_FREE_SCAL, PNG_FREE_SPLT,

2427

PNG_FREE_TEXT, PNG_FREE_UNKN,

2428

or simply PNG_FREE_ALL

2429

seq - sequence number of item to be freed

2430

(-1 for all items)

2431

2432

This function may be safely called when the relevant storage has

2433

already been freed, or has not yet been allocated, or was allocated

2434

by the user and not by libpng, and will in those cases do nothing.

2435

The "seq" parameter is ignored if only one item of the selected data

2436

type, such as PLTE, is allowed. If "seq" is not -1, and multiple items

2437

are allowed for the data type identified in the mask, such as text or

2438

sPLT, only the n'th item in the structure is freed, where n is "seq".

2439

2440

If you allocated data such as a palette that you passed in to libpng

2441

with png_set_*, you must not free it until just before the call to

2442

png_destroy_write_struct().

2443

2444

The default behavior is only to free data that was allocated internally

2445

by libpng. This can be changed, so that libpng will not free the data,

2446

or so that it will free data that was allocated by the user with png_malloc()

2447

or png_zalloc() and passed in via a png_set_*() function, with

2448

2449

png_data_freer(png_ptr, info_ptr, freer, mask)

2450

mask - which data elements are affected

2451

same choices as in png_free_data()

2452

freer - one of

2453

PNG_DESTROY_WILL_FREE_DATA

2454

PNG_SET_WILL_FREE_DATA

2455

PNG_USER_WILL_FREE_DATA

2456

2457

For example, to transfer responsibility for some data from a read structure

2458

to a write structure, you could use

2459

2460

png_data_freer(read_ptr, read_info_ptr,

2461

PNG_USER_WILL_FREE_DATA,

2462

PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)

2463

png_data_freer(write_ptr, write_info_ptr,

2464

PNG_DESTROY_WILL_FREE_DATA,

2465

PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)

2466

2467

thereby briefly reassigning responsibility for freeing to the user but

2468

immediately afterwards reassigning it once more to the write_destroy

2469

function. Having done this, it would then be safe to destroy the read

2470

structure and continue to use the PLTE, tRNS, and hIST data in the write

2471

structure.

2472

2473

This function only affects data that has already been allocated.

2474

You can call this function before calling after the png_set_*() functions

2475

to control whether the user or png_destroy_*() is supposed to free the data.

2476

When the user assumes responsibility for libpng-allocated data, the

2477

application must use

2478

png_free() to free it, and when the user transfers responsibility to libpng

2479

for data that the user has allocated, the user must have used png_malloc()

2480

or png_zalloc() to allocate it.

2481

2482

If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword

2483

separately, do not transfer responsibility for freeing text_ptr to libpng,

2484

because when libpng fills a png_text structure it combines these members with

2485

the key member, and png_free_data() will free only text_ptr.key. Similarly,

2486

if you transfer responsibility for free'ing text_ptr from libpng to your

2487

application, your application must not separately free those members.

2488

For a more compact example of writing a PNG image, see the file example.c.

2489

2490

V. Modifying/Customizing libpng:

2491

2492

There are two issues here. The first is changing how libpng does

2493

standard things like memory allocation, input/output, and error handling.

2494

The second deals with more complicated things like adding new chunks,

2495

adding new transformations, and generally changing how libpng works.

2496

Both of those are compile-time issues; that is, they are generally

2497

determined at the time the code is written, and there is rarely a need

2498

to provide the user with a means of changing them.

2499

2500

Memory allocation, input/output, and error handling

2501

2502

All of the memory allocation, input/output, and error handling in libpng

2503

goes through callbacks that are user-settable. The default routines are

2504

in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change

2505

these functions, call the appropriate png_set_*_fn() function.

2506

2507

Memory allocation is done through the functions png_malloc(), png_calloc(),

2508

and png_free(). These currently just call the standard C functions.

2509

png_calloc() calls png_malloc() and then png_memset() to clear the newly

2510

allocated memory to zero. If your pointers can't access more then 64K

2511

at a time, you will want to set MAXSEG_64K in zlib.h. Since it is

2512

unlikely that the method of handling memory allocation on a platform

2513

will change between applications, these functions must be modified in

2514

the library at compile time. If you prefer to use a different method

2515

of allocating and freeing data, you can use png_create_read_struct_2() or

2516

png_create_write_struct_2() to register your own functions as described

2517

above. These functions also provide a void pointer that can be retrieved

2518

via

2519

2520

mem_ptr=png_get_mem_ptr(png_ptr);

2521

2522

Your replacement memory functions must have prototypes as follows:

2523

2524

png_voidp malloc_fn(png_structp png_ptr,

2525

png_size_t size);

2526

void free_fn(png_structp png_ptr, png_voidp ptr);

2527

2528

Your malloc_fn() must return NULL in case of failure. The png_malloc()

2529

function will normally call png_error() if it receives a NULL from the

2530

system memory allocator or from your replacement malloc_fn().

2531

2532

Your free_fn() will never be called with a NULL ptr, since libpng's

2533

png_free() checks for NULL before calling free_fn().

2534

2535

Input/Output in libpng is done through png_read() and png_write(),

2536

which currently just call fread() and fwrite(). The FILE * is stored in

2537

png_struct and is initialized via png_init_io(). If you wish to change

2538

the method of I/O, the library supplies callbacks that you can set

2539

through the function png_set_read_fn() and png_set_write_fn() at run

2540

time, instead of calling the png_init_io() function. These functions

2541

also provide a void pointer that can be retrieved via the function

2542

png_get_io_ptr(). For example:

2543

2544

png_set_read_fn(png_structp read_ptr,

2545

voidp read_io_ptr, png_rw_ptr read_data_fn)

2546

2547

png_set_write_fn(png_structp write_ptr,

2548

voidp write_io_ptr, png_rw_ptr write_data_fn,

2549

png_flush_ptr output_flush_fn);

2550

2551

voidp read_io_ptr = png_get_io_ptr(read_ptr);

2552

voidp write_io_ptr = png_get_io_ptr(write_ptr);

2553

2554

The replacement I/O functions must have prototypes as follows:

2555

2556

void user_read_data(png_structp png_ptr,

2557

png_bytep data, png_size_t length);

2558

void user_write_data(png_structp png_ptr,

2559

png_bytep data, png_size_t length);

2560

void user_flush_data(png_structp png_ptr);

2561

2562

The user_read_data() function is responsible for detecting and

2563

handling end-of-data errors.

2564

2565

Supplying NULL for the read, write, or flush functions sets them back

2566

to using the default C stream functions, which expect the io_ptr to

2567

point to a standard *FILE structure. It is probably a mistake

2568

to use NULL for one of write_data_fn and output_flush_fn but not both

2569

of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.

2570

It is an error to read from a write stream, and vice versa.

2571

2572

Error handling in libpng is done through png_error() and png_warning().

2573

Errors handled through png_error() are fatal, meaning that png_error()

2574

should never return to its caller. Currently, this is handled via

2575

setjmp() and longjmp() (unless you have compiled libpng with

2576

PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),

2577

but you could change this to do things like exit() if you should wish.

2578

2579

On non-fatal errors, png_warning() is called

2580

to print a warning message, and then control returns to the calling code.

2581

By default png_error() and png_warning() print a message on stderr via

2582

fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined

2583

(because you don't want the messages) or PNG_NO_STDIO defined (because

2584

fprintf() isn't available). If you wish to change the behavior of the error

2585

functions, you will need to set up your own message callbacks. These

2586

functions are normally supplied at the time that the png_struct is created.

2587

It is also possible to redirect errors and warnings to your own replacement

2588

functions after png_create_*_struct() has been called by calling:

2589

2590

png_set_error_fn(png_structp png_ptr,

2591

png_voidp error_ptr, png_error_ptr error_fn,

2592

png_error_ptr warning_fn);

2593

2594

png_voidp error_ptr = png_get_error_ptr(png_ptr);

2595

2596

If NULL is supplied for either error_fn or warning_fn, then the libpng

2597

default function will be used, calling fprintf() and/or longjmp() if a

2598

problem is encountered. The replacement error functions should have

2599

parameters as follows:

2600

2601

void user_error_fn(png_structp png_ptr,

2602

png_const_charp error_msg);

2603

void user_warning_fn(png_structp png_ptr,

2604

png_const_charp warning_msg);

2605

2606

The motivation behind using setjmp() and longjmp() is the C++ throw and

2607

catch exception handling methods. This makes the code much easier to write,

2608

as there is no need to check every return code of every function call.

2609

However, there are some uncertainties about the status of local variables

2610

after a longjmp, so the user may want to be careful about doing anything

2611

after setjmp returns non-zero besides returning itself. Consult your

2612

compiler documentation for more details. For an alternative approach, you

2613

may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).

2614

2615

Custom chunks

2616

2617

If you need to read or write custom chunks, you may need to get deeper

2618

into the libpng code. The library now has mechanisms for storing

2619

and writing chunks of unknown type; you can even declare callbacks

2620

for custom chunks. However, this may not be good enough if the

2621

library code itself needs to know about interactions between your

2622

chunk and existing `intrinsic' chunks.

2623

2624

If you need to write a new intrinsic chunk, first read the PNG

2625

specification. Acquire a first level of understanding of how it works.

2626

Pay particular attention to the sections that describe chunk names,

2627

and look at how other chunks were designed, so you can do things

2628

similarly. Second, check out the sections of libpng that read and

2629

write chunks. Try to find a chunk that is similar to yours and use

2630

it as a template. More details can be found in the comments inside

2631

the code. It is best to handle unknown chunks in a generic method,

2632

via callback functions, instead of by modifying libpng functions.

2633

2634

If you wish to write your own transformation for the data, look through

2635

the part of the code that does the transformations, and check out some of

2636

the simpler ones to get an idea of how they work. Try to find a similar

2637

transformation to the one you want to add and copy off of it. More details

2638

can be found in the comments inside the code itself.

2639

2640

Configuring for 16 bit platforms

2641

2642

You will want to look into zconf.h to tell zlib (and thus libpng) that

2643

it cannot allocate more then 64K at a time. Even if you can, the memory

2644

won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.

2645

2646

Configuring for DOS

2647

2648

For DOS users who only have access to the lower 640K, you will

2649

have to limit zlib's memory usage via a png_set_compression_mem_level()

2650

call. See zlib.h or zconf.h in the zlib library for more information.

2651

2652

Configuring for Medium Model

2653

2654

Libpng's support for medium model has been tested on most of the popular

2655

compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets

2656

defined, and FAR gets defined to far in pngconf.h, and you should be

2657

all set. Everything in the library (except for zlib's structure) is

2658

expecting far data. You must use the typedefs with the p or pp on

2659

the end for pointers (or at least look at them and be careful). Make

2660

note that the rows of data are defined as png_bytepp, which is an

2661

unsigned char far * far *.

2662

2663

Configuring for gui/windowing platforms:

2664

2665

You will need to write new error and warning functions that use the GUI

2666

interface, as described previously, and set them to be the error and

2667

warning functions at the time that png_create_*_struct() is called,

2668

in order to have them available during the structure initialization.

2669

They can be changed later via png_set_error_fn(). On some compilers,

2670

you may also have to change the memory allocators (png_malloc, etc.).

2671

2672

Configuring for compiler xxx:

2673

2674

All includes for libpng are in pngconf.h. If you need to add, change

2675

or delete an include, this is the place to do it.

2676

The includes that are not needed outside libpng are protected by the

2677

PNG_INTERNAL definition, which is only defined for those routines inside

2678

libpng itself. The files in libpng proper only include png.h, which

2679

includes pngconf.h.

2680

2681

Configuring zlib:

2682

2683

There are special functions to configure the compression. Perhaps the

2684

most useful one changes the compression level, which currently uses

2685

input compression values in the range 0 - 9. The library normally

2686

uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests

2687

have shown that for a large majority of images, compression values in

2688

the range 3-6 compress nearly as well as higher levels, and do so much

2689

faster. For online applications it may be desirable to have maximum speed

2690

(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also

2691

specify no compression (Z_NO_COMPRESSION = 0), but this would create

2692

files larger than just storing the raw bitmap. You can specify the

2693

compression level by calling:

2694

2695

png_set_compression_level(png_ptr, level);

2696

2697

Another useful one is to reduce the memory level used by the library.

2698

The memory level defaults to 8, but it can be lowered if you are

2699

short on memory (running DOS, for example, where you only have 640K).

2700

Note that the memory level does have an effect on compression; among

2701

other things, lower levels will result in sections of incompressible

2702

data being emitted in smaller stored blocks, with a correspondingly

2703

larger relative overhead of up to 15% in the worst case.

2704

2705

png_set_compression_mem_level(png_ptr, level);

2706

2707

The other functions are for configuring zlib. They are not recommended

2708

for normal use and may result in writing an invalid PNG file. See

2709

zlib.h for more information on what these mean.

2710

2711

png_set_compression_strategy(png_ptr,

2712

strategy);

2713

png_set_compression_window_bits(png_ptr,

2714

window_bits);

2715

png_set_compression_method(png_ptr, method);

2716

png_set_compression_buffer_size(png_ptr, size);

2717

2718

Controlling row filtering

2719

2720

If you want to control whether libpng uses filtering or not, which

2721

filters are used, and how it goes about picking row filters, you

2722

can call one of these functions. The selection and configuration

2723

of row filters can have a significant impact on the size and

2724

encoding speed and a somewhat lesser impact on the decoding speed

2725

of an image. Filtering is enabled by default for RGB and grayscale

2726

images (with and without alpha), but not for paletted images nor

2727

for any images with bit depths less than 8 bits/pixel.

2728

2729

The 'method' parameter sets the main filtering method, which is

2730

currently only '0' in the PNG 1.2 specification. The 'filters'

2731

parameter sets which filter(s), if any, should be used for each

2732

scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS

2733

to turn filtering on and off, respectively.

2734

2735

Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,

2736

PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise

2737

ORed together with '|' to specify one or more filters to use.

2738

These filters are described in more detail in the PNG specification.

2739

If you intend to change the filter type during the course of writing

2740

the image, you should start with flags set for all of the filters

2741

you intend to use so that libpng can initialize its internal

2742

structures appropriately for all of the filter types. (Note that this

2743

means the first row must always be adaptively filtered, because libpng

2744

currently does not allocate the filter buffers until png_write_row()

2745

is called for the first time.)

2746

2747

filters = PNG_FILTER_NONE | PNG_FILTER_SUB

2748

PNG_FILTER_UP | PNG_FILTER_AVG |

2749

PNG_FILTER_PAETH | PNG_ALL_FILTERS;

2750

2751

png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,

2752

filters);

2753

The second parameter can also be

2754

PNG_INTRAPIXEL_DIFFERENCING if you are

2755

writing a PNG to be embedded in a MNG

2756

datastream. This parameter must be the

2757

same as the value of filter_method used

2758

in png_set_IHDR().

2759

2760

It is also possible to influence how libpng chooses from among the

2761

available filters. This is done in one or both of two ways - by

2762

telling it how important it is to keep the same filter for successive

2763

rows, and by telling it the relative computational costs of the filters.

2764

2765

double weights[3] = {1.5, 1.3, 1.1},

2766

costs[PNG_FILTER_VALUE_LAST] =

2767

{1.0, 1.3, 1.3, 1.5, 1.7};

2768

2769

png_set_filter_heuristics(png_ptr,

2770

PNG_FILTER_HEURISTIC_WEIGHTED, 3,

2771

weights, costs);

2772

2773

The weights are multiplying factors that indicate to libpng that the

2774

row filter should be the same for successive rows unless another row filter

2775

is that many times better than the previous filter. In the above example,

2776

if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a

2777

"sum of absolute differences" 1.5 x 1.3 times higher than other filters

2778

and still be chosen, while the NONE filter could have a sum 1.1 times

2779

higher than other filters and still be chosen. Unspecified weights are

2780

taken to be 1.0, and the specified weights should probably be declining

2781

like those above in order to emphasize recent filters over older filters.

2782

2783

The filter costs specify for each filter type a relative decoding cost

2784

to be considered when selecting row filters. This means that filters

2785

with higher costs are less likely to be chosen over filters with lower

2786

costs, unless their "sum of absolute differences" is that much smaller.

2787

The costs do not necessarily reflect the exact computational speeds of

2788

the various filters, since this would unduly influence the final image

2789

size.

2790

2791

Note that the numbers above were invented purely for this example and

2792

are given only to help explain the function usage. Little testing has

2793

been done to find optimum values for either the costs or the weights.

2794

2795

Removing unwanted object code

2796

2797

There are a bunch of #define's in pngconf.h that control what parts of

2798

libpng are compiled. All the defines end in _SUPPORTED. If you are

2799

never going to use a capability, you can change the #define to #undef

2800

before recompiling libpng and save yourself code and data space, or

2801

you can turn off individual capabilities with defines that begin with

2802

PNG_NO_.

2803

2804

You can also turn all of the transforms and ancillary chunk capabilities

2805

off en masse with compiler directives that define

2806

PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,

2807

or all four,

2808

along with directives to turn on any of the capabilities that you do

2809

want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra

2810

transformations but still leave the library fully capable of reading

2811

and writing PNG files with all known public chunks. Use of the

2812

PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library

2813

that is incapable of reading or writing ancillary chunks. If you are

2814

not using the progressive reading capability, you can turn that off

2815

with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING

2816

capability, which you'll still have).

2817

2818

All the reading and writing specific code are in separate files, so the

2819

linker should only grab the files it needs. However, if you want to

2820

make sure, or if you are building a stand alone library, all the

2821

reading files start with pngr and all the writing files start with

2822

pngw. The files that don't match either (like png.c, pngtrans.c, etc.)

2823

are used for both reading and writing, and always need to be included.

2824

The progressive reader is in pngpread.c

2825

2826

If you are creating or distributing a dynamically linked library (a .so

2827

or DLL file), you should not remove or disable any parts of the library,

2828

as this will cause applications linked with different versions of the

2829

library to fail if they call functions not available in your library.

2830

The size of the library itself should not be an issue, because only

2831

those sections that are actually used will be loaded into memory.

2832

2833

Requesting debug printout

2834

2835

The macro definition PNG_DEBUG can be used to request debugging

2836

printout. Set it to an integer value in the range 0 to 3. Higher

2837

numbers result in increasing amounts of debugging information. The

2838

information is printed to the "stderr" file, unless another file

2839

name is specified in the PNG_DEBUG_FILE macro definition.

2840

2841

When PNG_DEBUG > 0, the following functions (macros) become available:

2842

2843

png_debug(level, message)

2844

png_debug1(level, message, p1)

2845

png_debug2(level, message, p1, p2)

2846

2847

in which "level" is compared to PNG_DEBUG to decide whether to print

2848

the message, "message" is the formatted string to be printed,

2849

and p1 and p2 are parameters that are to be embedded in the string

2850

according to printf-style formatting directives. For example,

2851

2852

png_debug1(2, "foo=%d\n", foo);

2853

2854

is expanded to

2855

2856

if(PNG_DEBUG > 2)

2857

fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);

2858

2859

When PNG_DEBUG is defined but is zero, the macros aren't defined, but you

2860

can still use PNG_DEBUG to control your own debugging:

2861

2862

#ifdef PNG_DEBUG

2863

fprintf(stderr, ...

2864

#endif

2865

2866

When PNG_DEBUG = 1, the macros are defined, but only png_debug statements

2867

having level = 0 will be printed. There aren't any such statements in

2868

this version of libpng, but if you insert some they will be printed.

2869

2870

VI. MNG support

2871

2872

The MNG specification (available at http://www.libpng.org/pub/mng) allows

2873

certain extensions to PNG for PNG images that are embedded in MNG datastreams.

2874

Libpng can support some of these extensions. To enable them, use the

2875

png_permit_mng_features() function:

2876

2877

feature_set = png_permit_mng_features(png_ptr, mask)

2878

mask is a png_uint_32 containing the bitwise OR of the

2879

features you want to enable. These include

2880

PNG_FLAG_MNG_EMPTY_PLTE

2881

PNG_FLAG_MNG_FILTER_64

2882

PNG_ALL_MNG_FEATURES

2883

feature_set is a png_uint_32 that is the bitwise AND of

2884

your mask with the set of MNG features that is

2885

supported by the version of libpng that you are using.

2886

2887

It is an error to use this function when reading or writing a standalone

2888

PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped

2889

in a MNG datastream. As a minimum, it must have the MNG 8-byte signature

2890

and the MHDR and MEND chunks. Libpng does not provide support for these

2891

or any other MNG chunks; your application must provide its own support for

2892

them. You may wish to consider using libmng (available at

2893

http://www.libmng.com) instead.

2894

2895

VII. Changes to Libpng from version 0.88

2896

2897

It should be noted that versions of libpng later than 0.96 are not

2898

distributed by the original libpng author, Guy Schalnat, nor by

2899

Andreas Dilger, who had taken over from Guy during 1996 and 1997, and

2900

distributed versions 0.89 through 0.96, but rather by another member

2901

of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are

2902

still alive and well, but they have moved on to other things.

2903

2904

The old libpng functions png_read_init(), png_write_init(),

2905

png_info_init(), png_read_destroy(), and png_write_destroy() have been

2906

moved to PNG_INTERNAL in version 0.95 to discourage their use. These

2907

functions will be removed from libpng version 2.0.0.

2908

2909

The preferred method of creating and initializing the libpng structures is

2910

via the png_create_read_struct(), png_create_write_struct(), and

2911

png_create_info_struct() because they isolate the size of the structures

2912

from the application, allow version error checking, and also allow the

2913

use of custom error handling routines during the initialization, which

2914

the old functions do not. The functions png_read_destroy() and

2915

png_write_destroy() do not actually free the memory that libpng

2916

allocated for these structs, but just reset the data structures, so they

2917

can be used instead of png_destroy_read_struct() and

2918

png_destroy_write_struct() if you feel there is too much system overhead

2919

allocating and freeing the png_struct for each image read.

2920

2921

Setting the error callbacks via png_set_message_fn() before

2922

png_read_init() as was suggested in libpng-0.88 is no longer supported

2923

because this caused applications that do not use custom error functions

2924

to fail if the png_ptr was not initialized to zero. It is still possible

2925

to set the error callbacks AFTER png_read_init(), or to change them with

2926

png_set_error_fn(), which is essentially the same function, but with a new

2927

name to force compilation errors with applications that try to use the old

2928

method.

2929

2930

Starting with version 1.0.7, you can find out which version of the library

2931

you are using at run-time:

2932

2933

png_uint_32 libpng_vn = png_access_version_number();

2934

2935

The number libpng_vn is constructed from the major version, minor

2936

version with leading zero, and release number with leading zero,

2937

(e.g., libpng_vn for version 1.0.7 is 10007).

2938

2939

You can also check which version of png.h you used when compiling your

2940

application:

2941

2942

png_uint_32 application_vn = PNG_LIBPNG_VER;

2943

2944

VIII. Changes to Libpng from version 1.0.x to 1.2.x

2945

2946

Support for user memory management was enabled by default. To

2947

accomplish this, the functions png_create_read_struct_2(),

2948

png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),

2949

png_malloc_default(), and png_free_default() were added.

2950

2951

Support for the iTXt chunk has been enabled by default as of

2952

version 1.2.41.

2953

2954

Support for certain MNG features was enabled.

2955

2956

Support for numbered error messages was added. However, we never got

2957

around to actually numbering the error messages. The function

2958

png_set_strip_error_numbers() was added (Note: the prototype for this

2959

function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE

2960

builds of libpng-1.2.15. It was restored in libpng-1.2.36).

2961

2962

The png_malloc_warn() function was added at libpng-1.2.3. This issues

2963

a png_warning and returns NULL instead of aborting when it fails to

2964

acquire the requested memory allocation.

2965

2966

Support for setting user limits on image width and height was enabled

2967

by default. The functions png_set_user_limits(), png_get_user_width_max(),

2968

and png_get_user_height_max() were added at libpng-1.2.6.

2969

2970

The png_set_add_alpha() function was added at libpng-1.2.7.

2971

2972

The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.

2973

Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the

2974

tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is

2975

deprecated.

2976

2977

A number of macro definitions in support of runtime selection of

2978

assembler code features (especially Intel MMX code support) were

2979

added at libpng-1.2.0:

2980

2981

PNG_ASM_FLAG_MMX_SUPPORT_COMPILED

2982

PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU

2983

PNG_ASM_FLAG_MMX_READ_COMBINE_ROW

2984

PNG_ASM_FLAG_MMX_READ_INTERLACE

2985

PNG_ASM_FLAG_MMX_READ_FILTER_SUB

2986

PNG_ASM_FLAG_MMX_READ_FILTER_UP

2987

PNG_ASM_FLAG_MMX_READ_FILTER_AVG

2988

PNG_ASM_FLAG_MMX_READ_FILTER_PAETH

2989

PNG_ASM_FLAGS_INITIALIZED

2990

PNG_MMX_READ_FLAGS

2991

PNG_MMX_FLAGS

2992

PNG_MMX_WRITE_FLAGS

2993

PNG_MMX_FLAGS

2994

2995

We added the following functions in support of runtime

2996

selection of assembler code features:

2997

2998

png_get_mmx_flagmask()

2999

png_set_mmx_thresholds()

3000

png_get_asm_flags()

3001

png_get_mmx_bitdepth_threshold()

3002

png_get_mmx_rowbytes_threshold()

3003

png_set_asm_flags()

3004

3005

We replaced all of these functions with simple stubs in libpng-1.2.20,

3006

when the Intel assembler code was removed due to a licensing issue.

3007

3008

These macros are deprecated:

3009

3010

PNG_READ_TRANSFORMS_NOT_SUPPORTED

3011

PNG_PROGRESSIVE_READ_NOT_SUPPORTED

3012

PNG_NO_SEQUENTIAL_READ_SUPPORTED

3013

PNG_WRITE_TRANSFORMS_NOT_SUPPORTED

3014

PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED

3015

PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED

3016

3017

They have been replaced, respectively, by:

3018

3019

PNG_NO_READ_TRANSFORMS

3020

PNG_NO_PROGRESSIVE_READ

3021

PNG_NO_SEQUENTIAL_READ

3022

PNG_NO_WRITE_TRANSFORMS

3023

PNG_NO_READ_ANCILLARY_CHUNKS

3024

PNG_NO_WRITE_ANCILLARY_CHUNKS

3025

3026

PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been

3027

deprecated since libpng-1.0.16 and libpng-1.2.6.

3028

3029

The function

3030

png_check_sig(sig, num)

3031

was replaced with

3032

!png_sig_cmp(sig, 0, num)

3033

It has been deprecated since libpng-0.90.

3034

3035

The function

3036

png_set_gray_1_2_4_to_8()

3037

which also expands tRNS to alpha was replaced with

3038

png_set_expand_gray_1_2_4_to_8()

3039

which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.

3040

3041

IX. (Omitted)

3042

3043

3044

X. Detecting libpng

3045

3046

The png_get_io_ptr() function has been present since libpng-0.88, has never

3047

changed, and is unaffected by conditional compilation macros. It is the

3048

best choice for use in configure scripts for detecting the presence of any

3049

libpng version since 0.88. In an autoconf "configure.in" you could use

3050

3051

AC_CHECK_LIB(png, png_get_io_ptr, ...

3052

3053

XI. Source code repository

3054

3055

Since about February 2009, version 1.2.34, libpng has been under "git" source

3056

control. The git repository was built from old libpng-x.y.z.tar.gz files

3057

going back to version 0.70. You can access the git repository (read only)

3058

at

3059

3060

git://libpng.git.sourceforge.net/gitroot/libpng

3061

3062

or you can browse it via "gitweb" at

3063

3064

http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng

3065

3066

Patches can be sent to glennrp at users.sourceforge.net or to

3067

png-mng-implement at lists.sourceforge.net or you can upload them to

3068

the libpng bug tracker at

3069

3070

http://libpng.sourceforge.net

3071

3072

XII. Coding style

3073

3074

Our coding style is similar to the "Allman" style, with curly

3075

braces on separate lines:

3076

3077

if (condition)

3078

{

3079

action;

3080

}

3081

3082

else if (another condition)

3083

{

3084

another action;

3085

}

3086

3087

The braces can be omitted from simple one-line actions:

3088

3089

if (condition)

3090

return (0);

3091

3092

We use 3-space indentation, except for continued statements which

3093

are usually indented the same as the first line of the statement

3094

plus four more spaces.

3095

3096

For macro definitions we use 2-space indentation, always leaving the "#"

3097

in the first column.

3098

3099

#ifndef PNG_NO_FEATURE

3100

# ifndef PNG_FEATURE_SUPPORTED

3101

# define PNG_FEATURE_SUPPORTED

3102

# endif

3103

#endif

3104

3105

Comments appear with the leading "/*" at the same indentation as

3106

the statement that follows the comment:

3107

3108

/* Single-line comment */

3109

statement;

3110

3111

/* Multiple-line

3112

* comment

3113

*/

3114

statement;

3115

3116

Very short comments can be placed at the end of the statement

3117

to which they pertain:

3118

3119

statement; /* comment */

3120

3121

We don't use C++ style ("//") comments. We have, however,

3122

used them in the past in some now-abandoned MMX assembler

3123

code.

3124

3125

Functions and their curly braces are not indented, and

3126

exported functions are marked with PNGAPI:

3127

3128

/* This is a public function that is visible to

3129

* application programers. It does thus-and-so.

3130

*/

3131

void PNGAPI

3132

png_exported_function(png_ptr, png_info, foo)

3133

{

3134

body;

3135

}

3136

3137

The prototypes for all exported functions appear in png.h,

3138

above the comment that says

3139

3140

/* Maintainer: Put new public prototypes here ... */

3141

3142

We mark all non-exported functions with "/* PRIVATE */"":

3143

3144

void /* PRIVATE */

3145

png_non_exported_function(png_ptr, png_info, foo)

3146

{

3147

body;

3148

}

3149

3150

The prototypes for non-exported functions (except for those in

3151

pngtest) appear in

3152

the PNG_INTERNAL section of png.h

3153

above the comment that says

3154

3155

/* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */

3156

3157

The names of all exported functions and variables begin

3158

with "png_", and all publicly visible C preprocessor

3159

macros begin with "PNG_".

3160

3161

We put a space after each comma and after each semicolon

3162

in "for" statments, and we put spaces before and after each

3163

C binary operator and after "for" or "while". We don't

3164

put a space between a typecast and the expression being

3165

cast, nor do we put one between a function name and the

3166

left parenthesis that follows it:

3167

3168

for (i = 2; i > 0; --i)

3169

y[i] = a(x) + (int)b;

3170

3171

We prefer #ifdef and #ifndef to #if defined() and if !defined()

3172

when there is only one macro being tested.

3173

3174

We do not use the TAB character for indentation in the C sources.

3175

3176

Lines do not exceed 80 characters.

3177

3178

Other rules can be inferred by inspecting the libpng source.

3179

3180

XIII. Y2K Compliance in libpng

3181

3182

July 9, 2011

3183

3184

Since the PNG Development group is an ad-hoc body, we can't make

3185

an official declaration.

3186

3187

This is your unofficial assurance that libpng from version 0.71 and

3188

upward through 1.2.46 are Y2K compliant. It is my belief that earlier

3189

versions were also Y2K compliant.

3190

3191

Libpng only has three year fields. One is a 2-byte unsigned integer that

3192

will hold years up to 65535. The other two hold the date in text

3193

format, and will hold years up to 9999.

3194

3195

The integer is

3196

"png_uint_16 year" in png_time_struct.

3197

3198

The strings are

3199

"png_charp time_buffer" in png_struct and

3200

"near_time_buffer", which is a local character string in png.c.

3201

3202

There are seven time-related functions:

3203

3204

png_convert_to_rfc_1123() in png.c

3205

(formerly png_convert_to_rfc_1152() in error)

3206

png_convert_from_struct_tm() in pngwrite.c, called

3207

in pngwrite.c

3208

png_convert_from_time_t() in pngwrite.c

3209

png_get_tIME() in pngget.c

3210

png_handle_tIME() in pngrutil.c, called in pngread.c

3211

png_set_tIME() in pngset.c

3212

png_write_tIME() in pngwutil.c, called in pngwrite.c

3213

3214

All appear to handle dates properly in a Y2K environment. The

3215

png_convert_from_time_t() function calls gmtime() to convert from system

3216

clock time, which returns (year - 1900), which we properly convert to

3217

the full 4-digit year. There is a possibility that applications using

3218

libpng are not passing 4-digit years into the png_convert_to_rfc_1123()

3219

function, or that they are incorrectly passing only a 2-digit year

3220

instead of "year - 1900" into the png_convert_from_struct_tm() function,

3221

but this is not under our control. The libpng documentation has always

3222

stated that it works with 4-digit years, and the APIs have been

3223

documented as such.

3224

3225

The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned

3226

integer to hold the year, and can hold years as large as 65535.

3227

3228

zlib, upon which libpng depends, is also Y2K compliant. It contains

3229

no date-related code.

3230

3231

3232

Glenn Randers-Pehrson

3233

libpng maintainer

3234

PNG Development Group