~ubuntu-branches/ubuntu/maverick/libpng/maverick-updates : revision 24

1

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

2

3

libpng version 1.2.41 - December 3, 2009

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.41 - December 3, 2009

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.41, 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,

1053

<http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html>

1054

1055

1056

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

1057

1058

Libpng approximates this with

1059

1060

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

1061

1062

which can be expressed with integers as

1063

1064

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

1065

1066

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

1067

is known.

1068

1069

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

1070

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

1071

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

1072

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

1073

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

1074

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

1075

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

1076

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

1077

1078

png_color_16 my_background;

1079

png_color_16p image_background;

1080

1081

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

1082

png_set_background(png_ptr, image_background,

1083

PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);

1084

else

1085

png_set_background(png_ptr, &my_background,

1086

PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);

1087

1088

The png_set_background() function tells libpng to composite images

1089

with alpha or simple transparency against the supplied background

1090

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

1091

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

1092

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

1093

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

1094

display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file

1095

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

1096

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

1097

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

1098

1099

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

1100

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

1101

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

1102

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

1103

SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be

1104

correctly set.

1105

1106

Note that display_gamma is the overall gamma correction required to produce

1107

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

1108

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

1109

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

1110

a slightly smaller exponent is better.

1111

1112

double gamma, screen_gamma;

1113

1114

if (/* We have a user-defined screen

1115

gamma value */)

1116

{

1117

screen_gamma = user_defined_screen_gamma;

1118

}

1119

/* One way that applications can share the same

1120

screen gamma value */

1121

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

1122

!= NULL)

1123

{

1124

screen_gamma = (double)atof(gamma_str);

1125

}

1126

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

1127

else

1128

{

1129

screen_gamma = 2.2; /* A good guess for a

1130

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

1131

screen_gamma = 2.0; /* A good guess for a

1132

PC monitor in a dark room */

1133

screen_gamma = 1.7 or 1.0; /* A good

1134

guess for Mac systems */

1135

}

1136

1137

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

1138

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

1139

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

1140

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

1141

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

1142

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

1143

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

1144

recommended that PNG viewers support gamma correction.

1145

1146

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

1147

png_set_gamma(png_ptr, screen_gamma, gamma);

1148

else

1149

png_set_gamma(png_ptr, screen_gamma, 0.45455);

1150

1151

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

1152

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

1153

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

1154

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

1155

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

1156

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

1157

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

1158

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

1159

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

1160

histogram, it may not do as good a job.

1161

1162

if (color_type & PNG_COLOR_MASK_COLOR)

1163

{

1164

if (png_get_valid(png_ptr, info_ptr,

1165

PNG_INFO_PLTE))

1166

{

1167

png_uint_16p histogram = NULL;

1168

1169

png_get_hIST(png_ptr, info_ptr,

1170

&histogram);

1171

png_set_dither(png_ptr, palette, num_palette,

1172

max_screen_colors, histogram, 1);

1173

}

1174

else

1175

{

1176

png_color std_color_cube[MAX_SCREEN_COLORS] =

1177

{ ... colors ... };

1178

1179

png_set_dither(png_ptr, std_color_cube,

1180

MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,

1181

NULL,0);

1182

}

1183

}

1184

1185

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

1186

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

1187

zero):

1188

1189

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

1190

png_set_invert_mono(png_ptr);

1191

1192

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

1193

1194

if (color_type == PNG_COLOR_TYPE_GRAY ||

1195

color_type == PNG_COLOR_TYPE_GRAY_ALPHA)

1196

png_set_invert_mono(png_ptr);

1197

1198

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

1199

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

1200

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

1201

way PCs store them):

1202

1203

if (bit_depth == 16)

1204

png_set_swap(png_ptr);

1205

1206

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

1207

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

1208

1209

if (bit_depth < 8)

1210

png_set_packswap(png_ptr);

1211

1212

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

1213

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

1214

with

1215

1216

png_set_read_user_transform_fn(png_ptr,

1217

read_transform_fn);

1218

1219

You must supply the function

1220

1221

void read_transform_fn(png_ptr ptr, row_info_ptr

1222

row_info, png_bytep data)

1223

1224

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

1225

after all of the other transformations have been processed.

1226

1227

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

1228

callback function, and you can inform libpng that your transform

1229

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

1230

function

1231

1232

png_set_user_transform_info(png_ptr, user_ptr,

1233

user_depth, user_channels);

1234

1235

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

1236

freeing any memory required for the user structure.

1237

1238

You can retrieve the pointer via the function

1239

png_get_user_transform_ptr(). For example:

1240

1241

voidp read_user_transform_ptr =

1242

png_get_user_transform_ptr(png_ptr);

1243

1244

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

1245

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

1246

of the interlaced image.

1247

1248

number_of_passes = png_set_interlace_handling(png_ptr);

1249

1250

After setting the transformations, libpng can update your png_info

1251

structure to reflect any transformations you've requested with this

1252

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

1253

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

1254

will also update your palette with the correct screen_gamma and

1255

background if these have been given with the calls above.

1256

1257

png_read_update_info(png_ptr, info_ptr);

1258

1259

After you call png_read_update_info(), you can allocate any

1260

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

1261

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

1262

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

1263

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

1264

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

1265

of the functions below.

1266

1267

Reading image data

1268

1269

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

1270

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

1271

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

1272

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

1273

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

1274

an array of pointers to each row.

1275

1276

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

1277

to call png_set_interlace_handling() or call this function multiple

1278

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

1279

1280

png_read_image(png_ptr, row_pointers);

1281

1282

where row_pointers is:

1283

1284

png_bytep row_pointers[height];

1285

1286

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

1287

1288

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

1289

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

1290

interlace_type == PNG_INTERLACE_NONE), this is simple:

1291

1292

png_read_rows(png_ptr, row_pointers, NULL,

1293

number_of_rows);

1294

1295

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

1296

1297

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

1298

a single row_pointer instead of an array of row_pointers:

1299

1300

png_bytep row_pointer = row;

1301

png_read_row(png_ptr, row_pointer, NULL);

1302

1303

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

1304

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

1305

interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)

1306

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

1307

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

1308

on an 8x8 grid.

1309

1310

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

1311

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

1312

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

1313

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

1314

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

1315

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

1316

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

1317

rest of the image remaining whatever colors they were initialized to

1318

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

1319

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

1320

1321

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

1322

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

1323

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

1324

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

1325

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

1326

1327

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

1328

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

1329

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

1330

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

1331

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

1332

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

1333

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

1334

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

1335

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

1336

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

1337

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

1338

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

1339

numbered scanlines. Phew!

1340

1341

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

1342

png_start_read_image() or png_read_update_info():

1343

1344

if (interlace_type == PNG_INTERLACE_ADAM7)

1345

number_of_passes

1346

= png_set_interlace_handling(png_ptr);

1347

1348

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

1349

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

1350

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

1351

where it will return one pass.

1352

1353

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

1354

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

1355

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

1356

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

1357

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

1358

better looking one.

1359

1360

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

1361

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

1362

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

1363

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

1364

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

1365

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

1366

1367

png_read_rows(png_ptr, row_pointers, NULL,

1368

number_of_rows);

1369

1370

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

1371

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

1372

the second parameter NULL.

1373

1374

png_read_rows(png_ptr, NULL, row_pointers,

1375

number_of_rows);

1376

1377

Finishing a sequential read

1378

1379

After you are finished reading the image through the

1380

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

1381

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

1382

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

1383

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

1384

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

1385

1386

png_read_end(png_ptr, end_info);

1387

1388

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

1389

1390

png_destroy_read_struct(&png_ptr, &info_ptr,

1391

&end_info);

1392

1393

It is also possible to individually free the info_ptr members that

1394

point to libpng-allocated storage with the following function:

1395

1396

png_free_data(png_ptr, info_ptr, mask, seq)

1397

mask - identifies data to be freed, a mask

1398

containing the bitwise OR of one or

1399

more of

1400

PNG_FREE_PLTE, PNG_FREE_TRNS,

1401

PNG_FREE_HIST, PNG_FREE_ICCP,

1402

PNG_FREE_PCAL, PNG_FREE_ROWS,

1403

PNG_FREE_SCAL, PNG_FREE_SPLT,

1404

PNG_FREE_TEXT, PNG_FREE_UNKN,

1405

or simply PNG_FREE_ALL

1406

seq - sequence number of item to be freed

1407

(-1 for all items)

1408

1409

This function may be safely called when the relevant storage has

1410

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

1411

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

1412

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

1413

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

1414

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

1415

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

1416

1417

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

1418

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

1419

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

1420

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

1421

1422

png_data_freer(png_ptr, info_ptr, freer, mask)

1423

mask - which data elements are affected

1424

same choices as in png_free_data()

1425

freer - one of

1426

PNG_DESTROY_WILL_FREE_DATA

1427

PNG_SET_WILL_FREE_DATA

1428

PNG_USER_WILL_FREE_DATA

1429

1430

This function only affects data that has already been allocated.

1431

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

1432

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

1433

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

1434

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

1435

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

1436

responsibility for libpng-allocated data, the application must use

1437

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

1438

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

1439

or png_zalloc() to allocate it.

1440

1441

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

1442

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

1443

responsibility for freeing it to the png_set_rows or png_read_destroy function,

1444

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

1445

1446

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

1447

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

1448

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

1449

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

1450

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

1451

application, your application must not separately free those members.

1452

1453

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

1454

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

1455

your application instead of by libpng, you can use

1456

1457

png_set_invalid(png_ptr, info_ptr, mask);

1458

mask - identifies the chunks to be made invalid,

1459

containing the bitwise OR of one or

1460

more of

1461

PNG_INFO_gAMA, PNG_INFO_sBIT,

1462

PNG_INFO_cHRM, PNG_INFO_PLTE,

1463

PNG_INFO_tRNS, PNG_INFO_bKGD,

1464

PNG_INFO_hIST, PNG_INFO_pHYs,

1465

PNG_INFO_oFFs, PNG_INFO_tIME,

1466

PNG_INFO_pCAL, PNG_INFO_sRGB,

1467

PNG_INFO_iCCP, PNG_INFO_sPLT,

1468

PNG_INFO_sCAL, PNG_INFO_IDAT

1469

1470

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

1471

1472

Reading PNG files progressively

1473

1474

The progressive reader is slightly different then the non-progressive

1475

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

1476

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

1477

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

1478

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

1479

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

1480

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

1481

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

1482

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

1483

all of the code).

1484

1485

png_structp png_ptr;

1486

png_infop info_ptr;

1487

1488

/* An example code fragment of how you would

1489

initialize the progressive reader in your

1490

application. */

1491

int

1492

initialize_png_reader()

1493

{

1494

png_ptr = png_create_read_struct

1495

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1496

user_error_fn, user_warning_fn);

1497

if (!png_ptr)

1498

return (ERROR);

1499

info_ptr = png_create_info_struct(png_ptr);

1500

if (!info_ptr)

1501

{

1502

png_destroy_read_struct(&png_ptr, (png_infopp)NULL,

1503

(png_infopp)NULL);

1504

return (ERROR);

1505

}

1506

1507

if (setjmp(png_jmpbuf(png_ptr)))

1508

{

1509

png_destroy_read_struct(&png_ptr, &info_ptr,

1510

(png_infopp)NULL);

1511

return (ERROR);

1512

}

1513

1514

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

1515

to be called when the header info is valid,

1516

when each row is completed, and when the image

1517

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

1518

you can specify NULL parameters. Even when all

1519

three functions are NULL, you need to call

1520

png_set_progressive_read_fn(). You can use

1521

any struct as the user_ptr (cast to a void pointer

1522

for the function call), and retrieve the pointer

1523

from inside the callbacks using the function

1524

1525

png_get_progressive_ptr(png_ptr);

1526

1527

which will return a void pointer, which you have

1528

to cast appropriately.

1529

*/

1530

png_set_progressive_read_fn(png_ptr, (void *)user_ptr,

1531

info_callback, row_callback, end_callback);

1532

1533

return 0;

1534

}

1535

1536

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

1537

of data */

1538

int

1539

process_data(png_bytep buffer, png_uint_32 length)

1540

{

1541

if (setjmp(png_jmpbuf(png_ptr)))

1542

{

1543

png_destroy_read_struct(&png_ptr, &info_ptr,

1544

(png_infopp)NULL);

1545

return (ERROR);

1546

}

1547

1548

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

1549

of data from the file stream (in order, of

1550

course). On machines with segmented memory

1551

models machines, don't give it any more than

1552

64K. The library seems to run fine with sizes

1553

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

1554

necessary (I assume you can give it chunks of

1555

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

1556

yet). When this function returns, you may

1557

want to display any rows that were generated

1558

in the row callback if you don't already do

1559

so there.

1560

*/

1561

png_process_data(png_ptr, info_ptr, buffer, length);

1562

return 0;

1563

}

1564

1565

/* This function is called (as set by

1566

png_set_progressive_read_fn() above) when enough data

1567

has been supplied so all of the header has been

1568

read.

1569

*/

1570

void

1571

info_callback(png_structp png_ptr, png_infop info)

1572

{

1573

/* Do any setup here, including setting any of

1574

the transformations mentioned in the Reading

1575

PNG files section. For now, you _must_ call

1576

either png_start_read_image() or

1577

png_read_update_info() after all the

1578

transformations are set (even if you don't set

1579

any). You may start getting rows before

1580

png_process_data() returns, so this is your

1581

last chance to prepare for that.

1582

*/

1583

}

1584

1585

/* This function is called when each row of image

1586

data is complete */

1587

void

1588

row_callback(png_structp png_ptr, png_bytep new_row,

1589

png_uint_32 row_num, int pass)

1590

{

1591

/* If the image is interlaced, and you turned

1592

on the interlace handler, this function will

1593

be called for every row in every pass. Some

1594

of these rows will not be changed from the

1595

previous pass. When the row is not changed,

1596

the new_row variable will be NULL. The rows

1597

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

1598

really need the row_num and pass, but I'm

1599

supplying them because it may make your life

1600

easier.

1601

1602

For the non-NULL rows of interlaced images,

1603

you must call png_progressive_combine_row()

1604

passing in the row and the old row. You can

1605

call this function for NULL rows (it will just

1606

return) and for non-interlaced images (it just

1607

does the memcpy for you) if it will make the

1608

code easier. Thus, you can just do this for

1609

all cases:

1610

*/

1611

1612

png_progressive_combine_row(png_ptr, old_row,

1613

new_row);

1614

1615

/* where old_row is what was displayed for

1616

previously for the row. Note that the first

1617

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

1618

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

1619

initialized. After the first pass (and only

1620

for interlaced images), you will have to pass

1621

the current row, and the function will combine

1622

the old row and the new row.

1623

*/

1624

}

1625

1626

void

1627

end_callback(png_structp png_ptr, png_infop info)

1628

{

1629

/* This function is called after the whole image

1630

has been read, including any chunks after the

1631

image (up to and including the IEND). You

1632

will usually have the same info chunk as you

1633

had in the header, although some data may have

1634

been added to the comments and time fields.

1635

1636

Most people won't do much here, perhaps setting

1637

a flag that marks the image as finished.

1638

*/

1639

}

1640

1641

1642

1643

IV. Writing

1644

1645

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

1646

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

1647

back up in the reading section to understand writing.

1648

1649

Setup

1650

1651

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

1652

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

1653

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

1654

custom writing functions. See the discussion under Customizing libpng.

1655

1656

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

1657

if (!fp)

1658

{

1659

return (ERROR);

1660

}

1661

1662

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

1663

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

1664

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

1665

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

1666

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

1667

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

1668

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

1669

1670

png_structp png_ptr = png_create_write_struct

1671

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1672

user_error_fn, user_warning_fn);

1673

if (!png_ptr)

1674

return (ERROR);

1675

1676

png_infop info_ptr = png_create_info_struct(png_ptr);

1677

if (!info_ptr)

1678

{

1679

png_destroy_write_struct(&png_ptr,

1680

(png_infopp)NULL);

1681

return (ERROR);

1682

}

1683

1684

If you want to use your own memory allocation routines,

1685

define PNG_USER_MEM_SUPPORTED and use

1686

png_create_write_struct_2() instead of png_create_write_struct():

1687

1688

png_structp png_ptr = png_create_write_struct_2

1689

(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,

1690

user_error_fn, user_warning_fn, (png_voidp)

1691

user_mem_ptr, user_malloc_fn, user_free_fn);

1692

1693

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

1694

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

1695

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

1696

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

1697

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

1698

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

1699

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

1700

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

1701

the discussion on libpng error handling in the Customizing Libpng

1702

section below for more information on the libpng error handling.

1703

1704

if (setjmp(png_jmpbuf(png_ptr)))

1705

{

1706

png_destroy_write_struct(&png_ptr, &info_ptr);

1707

fclose(fp);

1708

return (ERROR);

1709

}

1710

...

1711

return;

1712

1713

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

1714

you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case

1715

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

1716

1717

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

1718

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

1719

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

1720

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

1721

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

1722

Libpng section below.

1723

1724

png_init_io(png_ptr, fp);

1725

1726

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

1727

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

1728

written the signature in your application, use

1729

1730

png_set_sig_bytes(png_ptr, 8);

1731

1732

to inform libpng that it should not write a signature.

1733

1734

Write callbacks

1735

1736

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

1737

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

1738

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

1739

You must supply a function

1740

1741

void write_row_callback(png_ptr, png_uint_32 row,

1742

int pass);

1743

{

1744

/* put your code here */

1745

}

1746

1747

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

1748

1749

To inform libpng about your function, use

1750

1751

png_set_write_status_fn(png_ptr, write_row_callback);

1752

1753

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

1754

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

1755

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

1756

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

1757

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

1758

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

1759

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

1760

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

1761

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

1762

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

1763

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

1764

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

1765

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

1766

filter types.

1767

1768

1769

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

1770

specific filters. You can use either a single

1771

PNG_FILTER_VALUE_NAME or the bitwise OR of one

1772

or more PNG_FILTER_NAME masks. */

1773

png_set_filter(png_ptr, 0,

1774

PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |

1775

PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |

1776

PNG_FILTER_UP | PNG_FILTER_VALUE_UP |

1777

PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |

1778

PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|

1779

PNG_ALL_FILTERS);

1780

1781

If an application

1782

wants to start and stop using particular filters during compression,

1783

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

1784

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

1785

and remove them after the start of compression.

1786

1787

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

1788

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

1789

1790

The png_set_compression_*() functions interface to the zlib compression

1791

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

1792

doing. The only generally useful call is png_set_compression_level()

1793

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

1794

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

1795

with zlib) for details on the compression levels.

1796

1797

/* set the zlib compression level */

1798

png_set_compression_level(png_ptr,

1799

Z_BEST_COMPRESSION);

1800

1801

/* set other zlib parameters */

1802

png_set_compression_mem_level(png_ptr, 8);

1803

png_set_compression_strategy(png_ptr,

1804

Z_DEFAULT_STRATEGY);

1805

png_set_compression_window_bits(png_ptr, 15);

1806

png_set_compression_method(png_ptr, 8);

1807

png_set_compression_buffer_size(png_ptr, 8192)

1808

1809

extern PNG_EXPORT(void,png_set_zbuf_size)

1810

1811

Setting the contents of info for output

1812

1813

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

1814

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

1815

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

1816

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

1817

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

1818

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

1819

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

1820

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

1821

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

1822

contain, see the PNG specification.

1823

1824

Some of the more important parts of the png_info are:

1825

1826

png_set_IHDR(png_ptr, info_ptr, width, height,

1827

bit_depth, color_type, interlace_type,

1828

compression_type, filter_method)

1829

width - holds the width of the image

1830

in pixels (up to 2^31).

1831

height - holds the height of the image

1832

in pixels (up to 2^31).

1833

bit_depth - holds the bit depth of one of the

1834

image channels.

1835

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

1836

and depend also on the

1837

color_type. See also significant

1838

bits (sBIT) below).

1839

color_type - describes which color/alpha

1840

channels are present.

1841

PNG_COLOR_TYPE_GRAY

1842

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

1843

PNG_COLOR_TYPE_GRAY_ALPHA

1844

(bit depths 8, 16)

1845

PNG_COLOR_TYPE_PALETTE

1846

(bit depths 1, 2, 4, 8)

1847

PNG_COLOR_TYPE_RGB

1848

(bit_depths 8, 16)

1849

PNG_COLOR_TYPE_RGB_ALPHA

1850

(bit_depths 8, 16)

1851

1852

PNG_COLOR_MASK_PALETTE

1853

PNG_COLOR_MASK_COLOR

1854

PNG_COLOR_MASK_ALPHA

1855

1856

interlace_type - PNG_INTERLACE_NONE or

1857

PNG_INTERLACE_ADAM7

1858

compression_type - (must be

1859

PNG_COMPRESSION_TYPE_DEFAULT)

1860

filter_method - (must be PNG_FILTER_TYPE_DEFAULT

1861

or, if you are writing a PNG to

1862

be embedded in a MNG datastream,

1863

can also be

1864

PNG_INTRAPIXEL_DIFFERENCING)

1865

1866

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

1867

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

1868

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

1869

in any order.

1870

1871

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

1872

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

1873

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

1874

1875

png_set_PLTE(png_ptr, info_ptr, palette,

1876

num_palette);

1877

palette - the palette for the file

1878

(array of png_color)

1879

num_palette - number of entries in the palette

1880

1881

png_set_gAMA(png_ptr, info_ptr, gamma);

1882

gamma - the gamma the image was created

1883

at (PNG_INFO_gAMA)

1884

1885

png_set_sRGB(png_ptr, info_ptr, srgb_intent);

1886

srgb_intent - the rendering intent

1887

(PNG_INFO_sRGB) The presence of

1888

the sRGB chunk means that the pixel

1889

data is in the sRGB color space.

1890

This chunk also implies specific

1891

values of gAMA and cHRM. Rendering

1892

intent is the CSS-1 property that

1893

has been defined by the International

1894

Color Consortium

1895

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

1896

It can be one of

1897

PNG_sRGB_INTENT_SATURATION,

1898

PNG_sRGB_INTENT_PERCEPTUAL,

1899

PNG_sRGB_INTENT_ABSOLUTE, or

1900

PNG_sRGB_INTENT_RELATIVE.

1901

1902

1903

png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,

1904

srgb_intent);

1905

srgb_intent - the rendering intent

1906

(PNG_INFO_sRGB) The presence of the

1907

sRGB chunk means that the pixel

1908

data is in the sRGB color space.

1909

This function also causes gAMA and

1910

cHRM chunks with the specific values

1911

that are consistent with sRGB to be

1912

written.

1913

1914

png_set_iCCP(png_ptr, info_ptr, name, compression_type,

1915

profile, proflen);

1916

name - The profile name.

1917

compression - The compression type; always

1918

PNG_COMPRESSION_TYPE_BASE for PNG 1.0.

1919

You may give NULL to this argument to

1920

ignore it.

1921

profile - International Color Consortium color

1922

profile data. May contain NULs.

1923

proflen - length of profile data in bytes.

1924

1925

png_set_sBIT(png_ptr, info_ptr, sig_bit);

1926

sig_bit - the number of significant bits for

1927

(PNG_INFO_sBIT) each of the gray, red,

1928

green, and blue channels, whichever are

1929

appropriate for the given color type

1930

(png_color_16)

1931

1932

png_set_tRNS(png_ptr, info_ptr, trans, num_trans,

1933

trans_values);

1934

trans - array of transparent

1935

entries for palette (PNG_INFO_tRNS)

1936

trans_values - graylevel or color sample values

1937

(in order red, green, blue) of the

1938

single transparent color for

1939

non-paletted images (PNG_INFO_tRNS)

1940

num_trans - number of transparent entries

1941

(PNG_INFO_tRNS)

1942

1943

png_set_hIST(png_ptr, info_ptr, hist);

1944

(PNG_INFO_hIST)

1945

hist - histogram of palette (array of

1946

png_uint_16)

1947

1948

png_set_tIME(png_ptr, info_ptr, mod_time);

1949

mod_time - time image was last modified

1950

(PNG_VALID_tIME)

1951

1952

png_set_bKGD(png_ptr, info_ptr, background);

1953

background - background color (PNG_VALID_bKGD)

1954

1955

png_set_text(png_ptr, info_ptr, text_ptr, num_text);

1956

text_ptr - array of png_text holding image

1957

comments

1958

text_ptr[i].compression - type of compression used

1959

on "text" PNG_TEXT_COMPRESSION_NONE

1960

PNG_TEXT_COMPRESSION_zTXt

1961

PNG_ITXT_COMPRESSION_NONE

1962

PNG_ITXT_COMPRESSION_zTXt

1963

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

1964

1-79 characters.

1965

text_ptr[i].text - text comments for current

1966

keyword. Can be NULL or empty.

1967

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

1968

after decompression, 0 for iTXt

1969

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

1970

after decompression, 0 for tEXt/zTXt

1971

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

1972

empty for unknown).

1973

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

1974

or empty for unknown).

1975

Note that the itxt_length, lang, and lang_key

1976

members of the text_ptr structure only exist

1977

when the library is built with iTXt chunk support.

1978

1979

num_text - number of comments

1980

1981

png_set_sPLT(png_ptr, info_ptr, &palette_ptr,

1982

num_spalettes);

1983

palette_ptr - array of png_sPLT_struct structures

1984

to be added to the list of palettes

1985

in the info structure.

1986

num_spalettes - number of palette structures to be

1987

added.

1988

1989

png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,

1990

unit_type);

1991

offset_x - positive offset from the left

1992

edge of the screen

1993

offset_y - positive offset from the top

1994

edge of the screen

1995

unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER

1996

1997

png_set_pHYs(png_ptr, info_ptr, res_x, res_y,

1998

unit_type);

1999

res_x - pixels/unit physical resolution

2000

in x direction

2001

res_y - pixels/unit physical resolution

2002

in y direction

2003

unit_type - PNG_RESOLUTION_UNKNOWN,

2004

PNG_RESOLUTION_METER

2005

2006

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

2007

unit - physical scale units (an integer)

2008

width - width of a pixel in physical scale units

2009

height - height of a pixel in physical scale units

2010

(width and height are doubles)

2011

2012

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

2013

unit - physical scale units (an integer)

2014

width - width of a pixel in physical scale units

2015

height - height of a pixel in physical scale units

2016

(width and height are strings like "2.54")

2017

2018

png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,

2019

num_unknowns)

2020

unknowns - array of png_unknown_chunk

2021

structures holding unknown chunks

2022

unknowns[i].name - name of unknown chunk

2023

unknowns[i].data - data of unknown chunk

2024

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

2025

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

2026

0: do not write chunk

2027

PNG_HAVE_IHDR: before PLTE

2028

PNG_HAVE_PLTE: before IDAT

2029

PNG_AFTER_IDAT: after IDAT

2030

2031

The "location" member is set automatically according to

2032

what part of the output file has already been written.

2033

You can change its value after calling png_set_unknown_chunks()

2034

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

2035

the chunks are sequenced according to their position in the

2036

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

2037

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

2038

png_set_unknown_chunks).

2039

2040

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

2041

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

2042

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

2043

and a compression type.

2044

2045

The compression types have the same valid numbers as the compression

2046

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

2047

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

2048

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

2049

text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.

2050

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

2051

specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt

2052

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

2053

2054

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

2055

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

2056

is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,

2057

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

2058

png_write_end() with the same struct.

2059

2060

The keywords that are given in the PNG Specification are:

2061

2062

Title Short (one line) title or

2063

caption for image

2064

Author Name of image's creator

2065

Description Description of image (possibly long)

2066

Copyright Copyright notice

2067

Creation Time Time of original image creation

2068

(usually RFC 1123 format, see below)

2069

Software Software used to create the image

2070

Disclaimer Legal disclaimer

2071

Warning Warning of nature of content

2072

Source Device used to create the image

2073

Comment Miscellaneous comment; conversion

2074

from other image format

2075

2076

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

2077

simple descriptions of what the comment is about. Some typical

2078

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

2079

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

2080

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

2081

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

2082

disclaimer until after, so viewers working over modem connections

2083

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

2084

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

2085

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

2086

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

2087

contain NUL characters, and should not contain control or other

2088

unprintable characters. To make the comments widely readable, stick

2089

with basic ASCII, and avoid machine specific character set extensions

2090

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

2091

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

2092

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

2093

is compressed anyway, so the compression would be meaningless.

2094

2095

PNG supports modification time via the png_time structure. Two

2096

conversion routines are provided, png_convert_from_time_t() for

2097

time_t and png_convert_from_struct_tm() for struct tm. The

2098

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

2099

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

2100

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

2101

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

2102

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

2103

that months start with 1.

2104

2105

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

2106

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

2107

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

2108

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

2109

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

2110

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

2111

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

2112

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

2113

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

2114

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

2115

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

2116

png_convert_to_rfc1123(png_timep) is provided to convert from PNG

2117

time to an RFC 1123 format string.

2118

2119

Writing unknown chunks

2120

2121

You can use the png_set_unknown_chunks function to queue up chunks

2122

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

2123

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

2124

png_write_info_before_PLTE, png_write_info, or png_write_end function.

2125

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

2126

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

2127

specification's ordering rules.

2128

2129

The high-level write interface

2130

2131

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

2132

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

2133

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

2134

in the info structure. All defined output

2135

transformations are permitted, enabled by the following masks.

2136

2137

PNG_TRANSFORM_IDENTITY No transformation

2138

PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples

2139

PNG_TRANSFORM_PACKSWAP Change order of packed

2140

pixels to LSB first

2141

PNG_TRANSFORM_INVERT_MONO Invert monochrome images

2142

PNG_TRANSFORM_SHIFT Normalize pixels to the

2143

sBIT depth

2144

PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA

2145

to BGRA

2146

PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA

2147

to AG

2148

PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity

2149

to transparency

2150

PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples

2151

PNG_TRANSFORM_STRIP_FILLER Strip out filler

2152

bytes (deprecated).

2153

PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading

2154

filler bytes

2155

PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing

2156

filler bytes

2157

2158

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

2159

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

2160

2161

png_write_png(png_ptr, info_ptr, png_transforms, NULL)

2162

2163

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

2164

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

2165

followed the set of transformations indicated by the transform mask,

2166

then png_write_image(), and finally png_write_end().

2167

2168

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

2169

to transformation parameters required by some future output transform.)

2170

2171

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

2172

when you use png_write_png().

2173

2174

The low-level write interface

2175

2176

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

2177

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

2178

this with a call to png_write_info().

2179

2180

png_write_info(png_ptr, info_ptr);

2181

2182

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

2183

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

2184

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

2185

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

2186

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

2187

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

2188

2189

png_set_invert_alpha(png_ptr);

2190

2191

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

2192

other transformations because in the case of paletted images the tRNS

2193

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

2194

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

2195

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

2196

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

2197

png_write_info() call.

2198

2199

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

2200

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

2201

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

2202

2203

png_write_info_before_PLTE(png_ptr, info_ptr);

2204

png_set_unknown_chunks(png_ptr, info_ptr, ...);

2205

png_write_info(png_ptr, info_ptr);

2206

2207

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

2208

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

2209

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

2210

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

2211

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

2212

certain color types and bit depths. Even though each transformation

2213

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

2214

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

2215

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

2216

2217

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

2218

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

2219

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

2220

bytes per pixel).

2221

2222

png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);

2223

2224

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

2225

PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel

2226

is stored XRGB or RGBX.

2227

2228

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

2229

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

2230

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

2231

correctly pack the pixels into a single byte:

2232

2233

png_set_packing(png_ptr);

2234

2235

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

2236

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

2237

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

2238

2239

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

2240

if (color_type & PNG_COLOR_MASK_COLOR)

2241

{

2242

sig_bit.red = true_bit_depth;

2243

sig_bit.green = true_bit_depth;

2244

sig_bit.blue = true_bit_depth;

2245

}

2246

else

2247

{

2248

sig_bit.gray = true_bit_depth;

2249

}

2250

if (color_type & PNG_COLOR_MASK_ALPHA)

2251

{

2252

sig_bit.alpha = true_bit_depth;

2253

}

2254

2255

png_set_sBIT(png_ptr, info_ptr, &sig_bit);

2256

2257

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

2258

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

2259

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

2260

is required by PNG.

2261

2262

png_set_shift(png_ptr, &sig_bit);

2263

2264

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

2265

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

2266

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

2267

first, the way PCs store them):

2268

2269

if (bit_depth > 8)

2270

png_set_swap(png_ptr);

2271

2272

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

2273

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

2274

2275

if (bit_depth < 8)

2276

png_set_packswap(png_ptr);

2277

2278

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

2279

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

2280

2281

png_set_bgr(png_ptr);

2282

2283

PNG files describe monochrome as black being zero and white being

2284

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

2285

(black being one and white being zero):

2286

2287

png_set_invert_mono(png_ptr);

2288

2289

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

2290

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

2291

with

2292

2293

png_set_write_user_transform_fn(png_ptr,

2294

write_transform_fn);

2295

2296

You must supply the function

2297

2298

void write_transform_fn(png_ptr ptr, row_info_ptr

2299

row_info, png_bytep data)

2300

2301

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

2302

before any of the other transformations are processed.

2303

2304

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

2305

callback function.

2306

2307

png_set_user_transform_info(png_ptr, user_ptr, 0, 0);

2308

2309

The user_channels and user_depth parameters of this function are ignored

2310

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

2311

2312

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

2313

For example:

2314

2315

voidp write_user_transform_ptr =

2316

png_get_user_transform_ptr(png_ptr);

2317

2318

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

2319

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

2320

flush the output stream a single time call:

2321

2322

png_write_flush(png_ptr);

2323

2324

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

2325

number of scanlines have been written, call:

2326

2327

png_set_flush(png_ptr, nrows);

2328

2329

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

2330

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

2331

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

2332

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

2333

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

2334

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

2335

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

2336

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

2337

only degrade the compression performance by a few percent over images

2338

that do not use flushing.

2339

2340

Writing the image data

2341

2342

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

2343

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

2344

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

2345

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

2346

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

2347

need to call png_set_interlace_handling() or call this function multiple

2348

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

2349

2350

png_write_image(png_ptr, row_pointers);

2351

2352

where row_pointers is:

2353

2354

png_byte *row_pointers[height];

2355

2356

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

2357

2358

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

2359

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

2360

this is simple:

2361

2362

png_write_rows(png_ptr, row_pointers,

2363

number_of_rows);

2364

2365

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

2366

2367

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

2368

a single row_pointer instead of an array of row_pointers:

2369

2370

png_bytep row_pointer = row;

2371

2372

png_write_row(png_ptr, row_pointer);

2373

2374

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

2375

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

2376

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

2377

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

2378

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

2379

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

2380

for details of which pixels to write when.

2381

2382

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

2383

use png_set_interlace_handling() and call png_write_rows() the

2384

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

2385

2386

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

2387

writing any rows:

2388

2389

number_of_passes =

2390

png_set_interlace_handling(png_ptr);

2391

2392

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

2393

but may change if another interlace type is added.

2394

2395

Then write the complete image number_of_passes times.

2396

2397

png_write_rows(png_ptr, row_pointers,

2398

number_of_rows);

2399

2400

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

2401

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

2402

the rows that are actually used.

2403

2404

Finishing a sequential write

2405

2406

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

2407

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

2408

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

2409

you can pass NULL.

2410

2411

png_write_end(png_ptr, info_ptr);

2412

2413

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

2414

2415

png_destroy_write_struct(&png_ptr, &info_ptr);

2416

2417

It is also possible to individually free the info_ptr members that

2418

point to libpng-allocated storage with the following function:

2419

2420

png_free_data(png_ptr, info_ptr, mask, seq)

2421

mask - identifies data to be freed, a mask

2422

containing the bitwise OR of one or

2423

more of

2424

PNG_FREE_PLTE, PNG_FREE_TRNS,

2425

PNG_FREE_HIST, PNG_FREE_ICCP,

2426

PNG_FREE_PCAL, PNG_FREE_ROWS,

2427

PNG_FREE_SCAL, PNG_FREE_SPLT,

2428

PNG_FREE_TEXT, PNG_FREE_UNKN,

2429

or simply PNG_FREE_ALL

2430

seq - sequence number of item to be freed

2431

(-1 for all items)

2432

2433

This function may be safely called when the relevant storage has

2434

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

2435

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

2436

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

2437

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

2438

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

2439

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

2440

2441

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

2442

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

2443

png_destroy_write_struct().

2444

2445

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

2446

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

2447

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

2448

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

2449

2450

png_data_freer(png_ptr, info_ptr, freer, mask)

2451

mask - which data elements are affected

2452

same choices as in png_free_data()

2453

freer - one of

2454

PNG_DESTROY_WILL_FREE_DATA

2455

PNG_SET_WILL_FREE_DATA

2456

PNG_USER_WILL_FREE_DATA

2457

2458

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

2459

to a write structure, you could use

2460

2461

png_data_freer(read_ptr, read_info_ptr,

2462

PNG_USER_WILL_FREE_DATA,

2463

PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)

2464

png_data_freer(write_ptr, write_info_ptr,

2465

PNG_DESTROY_WILL_FREE_DATA,

2466

PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)

2467

2468

thereby briefly reassigning responsibility for freeing to the user but

2469

immediately afterwards reassigning it once more to the write_destroy

2470

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

2471

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

2472

structure.

2473

2474

This function only affects data that has already been allocated.

2475

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

2476

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

2477

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

2478

application must use

2479

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

2480

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

2481

or png_zalloc() to allocate it.

2482

2483

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

2484

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

2485

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

2486

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

2487

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

2488

application, your application must not separately free those members.

2489

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

2490

2491

V. Modifying/Customizing libpng:

2492

2493

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

2494

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

2495

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

2496

adding new transformations, and generally changing how libpng works.

2497

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

2498

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

2499

to provide the user with a means of changing them.

2500

2501

Memory allocation, input/output, and error handling

2502

2503

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

2504

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

2505

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

2506

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

2507

2508

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

2509

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

2510

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

2511

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

2512

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

2513

unlikely that the method of handling memory allocation on a platform

2514

will change between applications, these functions must be modified in

2515

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

2516

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

2517

png_create_write_struct_2() to register your own functions as described

2518

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

2519

via

2520

2521

mem_ptr=png_get_mem_ptr(png_ptr);

2522

2523

Your replacement memory functions must have prototypes as follows:

2524

2525

png_voidp malloc_fn(png_structp png_ptr,

2526

png_size_t size);

2527

void free_fn(png_structp png_ptr, png_voidp ptr);

2528

2529

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

2530

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

2531

system memory allocator or from your replacement malloc_fn().

2532

2533

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

2534

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

2535

2536

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

2537

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

2538

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

2539

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

2540

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

2541

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

2542

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

2543

png_get_io_ptr(). For example:

2544

2545

png_set_read_fn(png_structp read_ptr,

2546

voidp read_io_ptr, png_rw_ptr read_data_fn)

2547

2548

png_set_write_fn(png_structp write_ptr,

2549

voidp write_io_ptr, png_rw_ptr write_data_fn,

2550

png_flush_ptr output_flush_fn);

2551

2552

voidp read_io_ptr = png_get_io_ptr(read_ptr);

2553

voidp write_io_ptr = png_get_io_ptr(write_ptr);

2554

2555

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

2556

2557

void user_read_data(png_structp png_ptr,

2558

png_bytep data, png_size_t length);

2559

void user_write_data(png_structp png_ptr,

2560

png_bytep data, png_size_t length);

2561

void user_flush_data(png_structp png_ptr);

2562

2563

The user_read_data() function is responsible for detecting and

2564

handling end-of-data errors.

2565

2566

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

2567

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

2568

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

2569

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

2570

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

2571

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

2572

2573

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

2574

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

2575

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

2576

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

2577

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

2578

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

2579

2580

On non-fatal errors, png_warning() is called

2581

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

2582

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

2583

fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined

2584

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

2585

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

2586

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

2587

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

2588

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

2589

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

2590

2591

png_set_error_fn(png_structp png_ptr,

2592

png_voidp error_ptr, png_error_ptr error_fn,

2593

png_error_ptr warning_fn);

2594

2595

png_voidp error_ptr = png_get_error_ptr(png_ptr);

2596

2597

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

2598

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

2599

problem is encountered. The replacement error functions should have

2600

parameters as follows:

2601

2602

void user_error_fn(png_structp png_ptr,

2603

png_const_charp error_msg);

2604

void user_warning_fn(png_structp png_ptr,

2605

png_const_charp warning_msg);

2606

2607

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

2608

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

2609

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

2610

However, there are some uncertainties about the status of local variables

2611

after a longjmp, so the user may want to be careful about doing anything

2612

after setjmp returns non-zero besides returning itself. Consult your

2613

compiler documentation for more details. For an alternative approach, you

2614

may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).

2615

2616

Custom chunks

2617

2618

If you need to read or write custom chunks, you may need to get deeper

2619

into the libpng code. The library now has mechanisms for storing

2620

and writing chunks of unknown type; you can even declare callbacks

2621

for custom chunks. However, this may not be good enough if the

2622

library code itself needs to know about interactions between your

2623

chunk and existing `intrinsic' chunks.

2624

2625

If you need to write a new intrinsic chunk, first read the PNG

2626

specification. Acquire a first level of understanding of how it works.

2627

Pay particular attention to the sections that describe chunk names,

2628

and look at how other chunks were designed, so you can do things

2629

similarly. Second, check out the sections of libpng that read and

2630

write chunks. Try to find a chunk that is similar to yours and use

2631

it as a template. More details can be found in the comments inside

2632

the code. It is best to handle unknown chunks in a generic method,

2633

via callback functions, instead of by modifying libpng functions.

2634

2635

If you wish to write your own transformation for the data, look through

2636

the part of the code that does the transformations, and check out some of

2637

the simpler ones to get an idea of how they work. Try to find a similar

2638

transformation to the one you want to add and copy off of it. More details

2639

can be found in the comments inside the code itself.

2640

2641

Configuring for 16 bit platforms

2642

2643

You will want to look into zconf.h to tell zlib (and thus libpng) that

2644

it cannot allocate more then 64K at a time. Even if you can, the memory

2645

won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.

2646

2647

Configuring for DOS

2648

2649

For DOS users who only have access to the lower 640K, you will

2650

have to limit zlib's memory usage via a png_set_compression_mem_level()

2651

call. See zlib.h or zconf.h in the zlib library for more information.

2652

2653

Configuring for Medium Model

2654

2655

Libpng's support for medium model has been tested on most of the popular

2656

compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets

2657

defined, and FAR gets defined to far in pngconf.h, and you should be

2658

all set. Everything in the library (except for zlib's structure) is

2659

expecting far data. You must use the typedefs with the p or pp on

2660

the end for pointers (or at least look at them and be careful). Make

2661

note that the rows of data are defined as png_bytepp, which is an

2662

unsigned char far * far *.

2663

2664

Configuring for gui/windowing platforms:

2665

2666

You will need to write new error and warning functions that use the GUI

2667

interface, as described previously, and set them to be the error and

2668

warning functions at the time that png_create_*_struct() is called,

2669

in order to have them available during the structure initialization.

2670

They can be changed later via png_set_error_fn(). On some compilers,

2671

you may also have to change the memory allocators (png_malloc, etc.).

2672

2673

Configuring for compiler xxx:

2674

2675

All includes for libpng are in pngconf.h. If you need to add, change

2676

or delete an include, this is the place to do it.

2677

The includes that are not needed outside libpng are protected by the

2678

PNG_INTERNAL definition, which is only defined for those routines inside

2679

libpng itself. The files in libpng proper only include png.h, which

2680

includes pngconf.h.

2681

2682

Configuring zlib:

2683

2684

There are special functions to configure the compression. Perhaps the

2685

most useful one changes the compression level, which currently uses

2686

input compression values in the range 0 - 9. The library normally

2687

uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests

2688

have shown that for a large majority of images, compression values in

2689

the range 3-6 compress nearly as well as higher levels, and do so much

2690

faster. For online applications it may be desirable to have maximum speed

2691

(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also

2692

specify no compression (Z_NO_COMPRESSION = 0), but this would create

2693

files larger than just storing the raw bitmap. You can specify the

2694

compression level by calling:

2695

2696

png_set_compression_level(png_ptr, level);

2697

2698

Another useful one is to reduce the memory level used by the library.

2699

The memory level defaults to 8, but it can be lowered if you are

2700

short on memory (running DOS, for example, where you only have 640K).

2701

Note that the memory level does have an effect on compression; among

2702

other things, lower levels will result in sections of incompressible

2703

data being emitted in smaller stored blocks, with a correspondingly

2704

larger relative overhead of up to 15% in the worst case.

2705

2706

png_set_compression_mem_level(png_ptr, level);

2707

2708

The other functions are for configuring zlib. They are not recommended

2709

for normal use and may result in writing an invalid PNG file. See

2710

zlib.h for more information on what these mean.

2711

2712

png_set_compression_strategy(png_ptr,

2713

strategy);

2714

png_set_compression_window_bits(png_ptr,

2715

window_bits);

2716

png_set_compression_method(png_ptr, method);

2717

png_set_compression_buffer_size(png_ptr, size);

2718

2719

Controlling row filtering

2720

2721

If you want to control whether libpng uses filtering or not, which

2722

filters are used, and how it goes about picking row filters, you

2723

can call one of these functions. The selection and configuration

2724

of row filters can have a significant impact on the size and

2725

encoding speed and a somewhat lesser impact on the decoding speed

2726

of an image. Filtering is enabled by default for RGB and grayscale

2727

images (with and without alpha), but not for paletted images nor

2728

for any images with bit depths less than 8 bits/pixel.

2729

2730

The 'method' parameter sets the main filtering method, which is

2731

currently only '0' in the PNG 1.2 specification. The 'filters'

2732

parameter sets which filter(s), if any, should be used for each

2733

scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS

2734

to turn filtering on and off, respectively.

2735

2736

Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,

2737

PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise

2738

ORed together with '|' to specify one or more filters to use.

2739

These filters are described in more detail in the PNG specification.

2740

If you intend to change the filter type during the course of writing

2741

the image, you should start with flags set for all of the filters

2742

you intend to use so that libpng can initialize its internal

2743

structures appropriately for all of the filter types. (Note that this

2744

means the first row must always be adaptively filtered, because libpng

2745

currently does not allocate the filter buffers until png_write_row()

2746

is called for the first time.)

2747

2748

filters = PNG_FILTER_NONE | PNG_FILTER_SUB

2749

PNG_FILTER_UP | PNG_FILTER_AVG |

2750

PNG_FILTER_PAETH | PNG_ALL_FILTERS;

2751

2752

png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,

2753

filters);

2754

The second parameter can also be

2755

PNG_INTRAPIXEL_DIFFERENCING if you are

2756

writing a PNG to be embedded in a MNG

2757

datastream. This parameter must be the

2758

same as the value of filter_method used

2759

in png_set_IHDR().

2760

2761

It is also possible to influence how libpng chooses from among the

2762

available filters. This is done in one or both of two ways - by

2763

telling it how important it is to keep the same filter for successive

2764

rows, and by telling it the relative computational costs of the filters.

2765

2766

double weights[3] = {1.5, 1.3, 1.1},

2767

costs[PNG_FILTER_VALUE_LAST] =

2768

{1.0, 1.3, 1.3, 1.5, 1.7};

2769

2770

png_set_filter_heuristics(png_ptr,

2771

PNG_FILTER_HEURISTIC_WEIGHTED, 3,

2772

weights, costs);

2773

2774

The weights are multiplying factors that indicate to libpng that the

2775

row filter should be the same for successive rows unless another row filter

2776

is that many times better than the previous filter. In the above example,

2777

if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a

2778

"sum of absolute differences" 1.5 x 1.3 times higher than other filters

2779

and still be chosen, while the NONE filter could have a sum 1.1 times

2780

higher than other filters and still be chosen. Unspecified weights are

2781

taken to be 1.0, and the specified weights should probably be declining

2782

like those above in order to emphasize recent filters over older filters.

2783

2784

The filter costs specify for each filter type a relative decoding cost

2785

to be considered when selecting row filters. This means that filters

2786

with higher costs are less likely to be chosen over filters with lower

2787

costs, unless their "sum of absolute differences" is that much smaller.

2788

The costs do not necessarily reflect the exact computational speeds of

2789

the various filters, since this would unduly influence the final image

2790

size.

2791

2792

Note that the numbers above were invented purely for this example and

2793

are given only to help explain the function usage. Little testing has

2794

been done to find optimum values for either the costs or the weights.

2795

2796

Removing unwanted object code

2797

2798

There are a bunch of #define's in pngconf.h that control what parts of

2799

libpng are compiled. All the defines end in _SUPPORTED. If you are

2800

never going to use a capability, you can change the #define to #undef

2801

before recompiling libpng and save yourself code and data space, or

2802

you can turn off individual capabilities with defines that begin with

2803

PNG_NO_.

2804

2805

You can also turn all of the transforms and ancillary chunk capabilities

2806

off en masse with compiler directives that define

2807

PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,

2808

or all four,

2809

along with directives to turn on any of the capabilities that you do

2810

want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra

2811

transformations but still leave the library fully capable of reading

2812

and writing PNG files with all known public chunks. Use of the

2813

PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library

2814

that is incapable of reading or writing ancillary chunks. If you are

2815

not using the progressive reading capability, you can turn that off

2816

with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING

2817

capability, which you'll still have).

2818

2819

All the reading and writing specific code are in separate files, so the

2820

linker should only grab the files it needs. However, if you want to

2821

make sure, or if you are building a stand alone library, all the

2822

reading files start with pngr and all the writing files start with

2823

pngw. The files that don't match either (like png.c, pngtrans.c, etc.)

2824

are used for both reading and writing, and always need to be included.

2825

The progressive reader is in pngpread.c

2826

2827

If you are creating or distributing a dynamically linked library (a .so

2828

or DLL file), you should not remove or disable any parts of the library,

2829

as this will cause applications linked with different versions of the

2830

library to fail if they call functions not available in your library.

2831

The size of the library itself should not be an issue, because only

2832

those sections that are actually used will be loaded into memory.

2833

2834

Requesting debug printout

2835

2836

The macro definition PNG_DEBUG can be used to request debugging

2837

printout. Set it to an integer value in the range 0 to 3. Higher

2838

numbers result in increasing amounts of debugging information. The

2839

information is printed to the "stderr" file, unless another file

2840

name is specified in the PNG_DEBUG_FILE macro definition.

2841

2842

When PNG_DEBUG > 0, the following functions (macros) become available:

2843

2844

png_debug(level, message)

2845

png_debug1(level, message, p1)

2846

png_debug2(level, message, p1, p2)

2847

2848

in which "level" is compared to PNG_DEBUG to decide whether to print

2849

the message, "message" is the formatted string to be printed,

2850

and p1 and p2 are parameters that are to be embedded in the string

2851

according to printf-style formatting directives. For example,

2852

2853

png_debug1(2, "foo=%d\n", foo);

2854

2855

is expanded to

2856

2857

if(PNG_DEBUG > 2)

2858

fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);

2859

2860

When PNG_DEBUG is defined but is zero, the macros aren't defined, but you

2861

can still use PNG_DEBUG to control your own debugging:

2862

2863

#ifdef PNG_DEBUG

2864

fprintf(stderr, ...

2865

#endif

2866

2867

When PNG_DEBUG = 1, the macros are defined, but only png_debug statements

2868

having level = 0 will be printed. There aren't any such statements in

2869

this version of libpng, but if you insert some they will be printed.

2870

2871

VI. MNG support

2872

2873

The MNG specification (available at http://www.libpng.org/pub/mng) allows

2874

certain extensions to PNG for PNG images that are embedded in MNG datastreams.

2875

Libpng can support some of these extensions. To enable them, use the

2876

png_permit_mng_features() function:

2877

2878

feature_set = png_permit_mng_features(png_ptr, mask)

2879

mask is a png_uint_32 containing the bitwise OR of the

2880

features you want to enable. These include

2881

PNG_FLAG_MNG_EMPTY_PLTE

2882

PNG_FLAG_MNG_FILTER_64

2883

PNG_ALL_MNG_FEATURES

2884

feature_set is a png_uint_32 that is the bitwise AND of

2885

your mask with the set of MNG features that is

2886

supported by the version of libpng that you are using.

2887

2888

It is an error to use this function when reading or writing a standalone

2889

PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped

2890

in a MNG datastream. As a minimum, it must have the MNG 8-byte signature

2891

and the MHDR and MEND chunks. Libpng does not provide support for these

2892

or any other MNG chunks; your application must provide its own support for

2893

them. You may wish to consider using libmng (available at

2894

http://www.libmng.com) instead.

2895

2896

VII. Changes to Libpng from version 0.88

2897

2898

It should be noted that versions of libpng later than 0.96 are not

2899

distributed by the original libpng author, Guy Schalnat, nor by

2900

Andreas Dilger, who had taken over from Guy during 1996 and 1997, and

2901

distributed versions 0.89 through 0.96, but rather by another member

2902

of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are

2903

still alive and well, but they have moved on to other things.

2904

2905

The old libpng functions png_read_init(), png_write_init(),

2906

png_info_init(), png_read_destroy(), and png_write_destroy() have been

2907

moved to PNG_INTERNAL in version 0.95 to discourage their use. These

2908

functions will be removed from libpng version 2.0.0.

2909

2910

The preferred method of creating and initializing the libpng structures is

2911

via the png_create_read_struct(), png_create_write_struct(), and

2912

png_create_info_struct() because they isolate the size of the structures

2913

from the application, allow version error checking, and also allow the

2914

use of custom error handling routines during the initialization, which

2915

the old functions do not. The functions png_read_destroy() and

2916

png_write_destroy() do not actually free the memory that libpng

2917

allocated for these structs, but just reset the data structures, so they

2918

can be used instead of png_destroy_read_struct() and

2919

png_destroy_write_struct() if you feel there is too much system overhead

2920

allocating and freeing the png_struct for each image read.

2921

2922

Setting the error callbacks via png_set_message_fn() before

2923

png_read_init() as was suggested in libpng-0.88 is no longer supported

2924

because this caused applications that do not use custom error functions

2925

to fail if the png_ptr was not initialized to zero. It is still possible

2926

to set the error callbacks AFTER png_read_init(), or to change them with

2927

png_set_error_fn(), which is essentially the same function, but with a new

2928

name to force compilation errors with applications that try to use the old

2929

method.

2930

2931

Starting with version 1.0.7, you can find out which version of the library

2932

you are using at run-time:

2933

2934

png_uint_32 libpng_vn = png_access_version_number();

2935

2936

The number libpng_vn is constructed from the major version, minor

2937

version with leading zero, and release number with leading zero,

2938

(e.g., libpng_vn for version 1.0.7 is 10007).

2939

2940

You can also check which version of png.h you used when compiling your

2941

application:

2942

2943

png_uint_32 application_vn = PNG_LIBPNG_VER;

2944

2945

VIII. Changes to Libpng from version 1.0.x to 1.2.x

2946

2947

Support for user memory management was enabled by default. To

2948

accomplish this, the functions png_create_read_struct_2(),

2949

png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),

2950

png_malloc_default(), and png_free_default() were added.

2951

2952

Support for the iTXt chunk has been enabled by default as of

2953

version 1.2.41.

2954

2955

Support for certain MNG features was enabled.

2956

2957

Support for numbered error messages was added. However, we never got

2958

around to actually numbering the error messages. The function

2959

png_set_strip_error_numbers() was added (Note: the prototype for this

2960

function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE

2961

builds of libpng-1.2.15. It was restored in libpng-1.2.36).

2962

2963

The png_malloc_warn() function was added at libpng-1.2.3. This issues

2964

a png_warning and returns NULL instead of aborting when it fails to

2965

acquire the requested memory allocation.

2966

2967

Support for setting user limits on image width and height was enabled

2968

by default. The functions png_set_user_limits(), png_get_user_width_max(),

2969

and png_get_user_height_max() were added at libpng-1.2.6.

2970

2971

The png_set_add_alpha() function was added at libpng-1.2.7.

2972

2973

The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.

2974

Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the

2975

tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is

2976

deprecated.

2977

2978

A number of macro definitions in support of runtime selection of

2979

assembler code features (especially Intel MMX code support) were

2980

added at libpng-1.2.0:

2981

2982

PNG_ASM_FLAG_MMX_SUPPORT_COMPILED

2983

PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU

2984

PNG_ASM_FLAG_MMX_READ_COMBINE_ROW

2985

PNG_ASM_FLAG_MMX_READ_INTERLACE

2986

PNG_ASM_FLAG_MMX_READ_FILTER_SUB

2987

PNG_ASM_FLAG_MMX_READ_FILTER_UP

2988

PNG_ASM_FLAG_MMX_READ_FILTER_AVG

2989

PNG_ASM_FLAG_MMX_READ_FILTER_PAETH

2990

PNG_ASM_FLAGS_INITIALIZED

2991

PNG_MMX_READ_FLAGS

2992

PNG_MMX_FLAGS

2993

PNG_MMX_WRITE_FLAGS

2994

PNG_MMX_FLAGS

2995

2996

We added the following functions in support of runtime

2997

selection of assembler code features:

2998

2999

png_get_mmx_flagmask()

3000

png_set_mmx_thresholds()

3001

png_get_asm_flags()

3002

png_get_mmx_bitdepth_threshold()

3003

png_get_mmx_rowbytes_threshold()

3004

png_set_asm_flags()

3005

3006

We replaced all of these functions with simple stubs in libpng-1.2.20,

3007

when the Intel assembler code was removed due to a licensing issue.

3008

3009

These macros are deprecated:

3010

3011

PNG_READ_TRANSFORMS_NOT_SUPPORTED

3012

PNG_PROGRESSIVE_READ_NOT_SUPPORTED

3013

PNG_NO_SEQUENTIAL_READ_SUPPORTED

3014

PNG_WRITE_TRANSFORMS_NOT_SUPPORTED

3015

PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED

3016

PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED

3017

3018

They have been replaced, respectively, by:

3019

3020

PNG_NO_READ_TRANSFORMS

3021

PNG_NO_PROGRESSIVE_READ

3022

PNG_NO_SEQUENTIAL_READ

3023

PNG_NO_WRITE_TRANSFORMS

3024

PNG_NO_READ_ANCILLARY_CHUNKS

3025

PNG_NO_WRITE_ANCILLARY_CHUNKS

3026

3027

PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been

3028

deprecated since libpng-1.0.16 and libpng-1.2.6.

3029

3030

The function

3031

png_check_sig(sig, num)

3032

was replaced with

3033

!png_sig_cmp(sig, 0, num)

3034

It has been deprecated since libpng-0.90.

3035

3036

The function

3037

png_set_gray_1_2_4_to_8()

3038

which also expands tRNS to alpha was replaced with

3039

png_set_expand_gray_1_2_4_to_8()

3040

which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.

3041

IX. (Omitted)

3042

X. Detecting libpng

3043

3044

The png_get_io_ptr() function has been present since libpng-0.88, has never

3045

changed, and is unaffected by conditional compilation macros. It is the

3046

best choice for use in configure scripts for detecting the presence of any

3047

libpng version since 0.88. In an autoconf "configure.in" you could use

3048

3049

AC_CHECK_LIB(png, png_get_io_ptr, ...

3050

3051

XI. Source code repository

3052

3053

Since about February 2009, version 1.2.34, libpng has been under "git" source

3054

control. The git repository was built from old libpng-x.y.z.tar.gz files

3055

going back to version 0.70. You can access the git repository (read only)

3056

at

3057

3058

git://libpng.git.sourceforge.net/gitroot/libpng

3059

3060

or you can browse it via "gitweb" at

3061

3062

http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng

3063

3064

Patches can be sent to glennrp at users.sourceforge.net or to

3065

png-mng-implement at lists.sourceforge.net or you can upload them to

3066

the libpng bug tracker at

3067

3068

http://libpng.sourceforge.net

3069

3070

XII. Coding style

3071

3072

Our coding style is similar to the "Allman" style, with curly

3073

braces on separate lines:

3074

3075

if (condition)

3076

{

3077

action;

3078

}

3079

3080

else if (another condition)

3081

{

3082

another action;

3083

}

3084

3085

The braces can be omitted from simple one-line actions:

3086

3087

if (condition)

3088

return (0);

3089

3090

We use 3-space indentation, except for continued statements which

3091

are usually indented the same as the first line of the statement

3092

plus four more spaces.

3093

3094

For macro definitions we use 2-space indentation, always leaving the "#"

3095

in the first column.

3096

3097

#ifndef PNG_NO_FEATURE

3098

# ifndef PNG_FEATURE_SUPPORTED

3099

# define PNG_FEATURE_SUPPORTED

3100

# endif

3101

#endif

3102

3103

Comments appear with the leading "/*" at the same indentation as

3104

the statement that follows the comment:

3105

3106

/* Single-line comment */

3107

statement;

3108

3109

/* Multiple-line

3110

* comment

3111

*/

3112

statement;

3113

3114

Very short comments can be placed at the end of the statement

3115

to which they pertain:

3116

3117

statement; /* comment */

3118

3119

We don't use C++ style ("//") comments. We have, however,

3120

used them in the past in some now-abandoned MMX assembler

3121

code.

3122

3123

Functions and their curly braces are not indented, and

3124

exported functions are marked with PNGAPI:

3125

3126

/* This is a public function that is visible to

3127

* application programers. It does thus-and-so.

3128

*/

3129

void PNGAPI

3130

png_exported_function(png_ptr, png_info, foo)

3131

{

3132

body;

3133

}

3134

3135

The prototypes for all exported functions appear in png.h,

3136

above the comment that says

3137

3138

/* Maintainer: Put new public prototypes here ... */

3139

3140

We mark all non-exported functions with "/* PRIVATE */"":

3141

3142

void /* PRIVATE */

3143

png_non_exported_function(png_ptr, png_info, foo)

3144

{

3145

body;

3146

}

3147

3148

The prototypes for non-exported functions (except for those in

3149

pngtest) appear in

3150

the PNG_INTERNAL section of png.h

3151

above the comment that says

3152

3153

/* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */

3154

3155

The names of all exported functions and variables begin

3156

with "png_", and all publicly visible C preprocessor

3157

macros begin with "PNG_".

3158

3159

We put a space after each comma and after each semicolon

3160

in "for" statments, and we put spaces before and after each

3161

C binary operator and after "for" or "while". We don't

3162

put a space between a typecast and the expression being

3163

cast, nor do we put one between a function name and the

3164

left parenthesis that follows it:

3165

3166

for (i = 2; i > 0; --i)

3167

y[i] = a(x) + (int)b;

3168

3169

We prefer #ifdef and #ifndef to #if defined() and if !defined()

3170

when there is only one macro being tested.

3171

3172

We do not use the TAB character for indentation in the C sources.

3173

3174

Other rules can be inferred by inspecting the libpng source.

3175

3176

XIII. Y2K Compliance in libpng

3177

3178

December 3, 2009

3179

3180

Since the PNG Development group is an ad-hoc body, we can't make

3181

an official declaration.

3182

3183

This is your unofficial assurance that libpng from version 0.71 and

3184

upward through 1.2.41 are Y2K compliant. It is my belief that earlier

3185

versions were also Y2K compliant.

3186

3187

Libpng only has three year fields. One is a 2-byte unsigned integer that

3188

will hold years up to 65535. The other two hold the date in text

3189

format, and will hold years up to 9999.

3190

3191

The integer is

3192

"png_uint_16 year" in png_time_struct.

3193

3194

The strings are

3195

"png_charp time_buffer" in png_struct and

3196

"near_time_buffer", which is a local character string in png.c.

3197

3198

There are seven time-related functions:

3199

3200

png_convert_to_rfc_1123() in png.c

3201

(formerly png_convert_to_rfc_1152() in error)

3202

png_convert_from_struct_tm() in pngwrite.c, called

3203

in pngwrite.c

3204

png_convert_from_time_t() in pngwrite.c

3205

png_get_tIME() in pngget.c

3206

png_handle_tIME() in pngrutil.c, called in pngread.c

3207

png_set_tIME() in pngset.c

3208

png_write_tIME() in pngwutil.c, called in pngwrite.c

3209

3210

All appear to handle dates properly in a Y2K environment. The

3211

png_convert_from_time_t() function calls gmtime() to convert from system

3212

clock time, which returns (year - 1900), which we properly convert to

3213

the full 4-digit year. There is a possibility that applications using

3214

libpng are not passing 4-digit years into the png_convert_to_rfc_1123()

3215

function, or that they are incorrectly passing only a 2-digit year

3216

instead of "year - 1900" into the png_convert_from_struct_tm() function,

3217

but this is not under our control. The libpng documentation has always

3218

stated that it works with 4-digit years, and the APIs have been

3219

documented as such.

3220

3221

The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned

3222

integer to hold the year, and can hold years as large as 65535.

3223

3224

zlib, upon which libpng depends, is also Y2K compliant. It contains

3225

no date-related code.

3226

3227

3228

Glenn Randers-Pehrson

3229

libpng maintainer

3230

PNG Development Group