### Initialize and Decompress Stream in C

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/examples/zlib_how.html

This C code snippet shows the initialization and setup for decompressing a zlib stream using the inflate() routine. It details the allocation of the z_stream structure, setting necessary fields like zalloc, zfree, and avail_in, and calling inflateInit() to prepare for decompression. Error handling for inflateInit() is also included.

```c
/* Decompress from file source to file dest until stream ends or EOF.
   inf() returns Z_OK on success, Z_MEM_ERROR if memory could not be
   allocated for processing, Z_DATA_ERROR if the deflate data is
   invalid or incomplete, Z_VERSION_ERROR if the version of zlib.h and
   the version of the library linked do not match, or Z_ERRNO if there
   is an error reading or writing the files. */
int inf(FILE *source, FILE *dest)
{
    int ret;
    unsigned have;
    z_stream strm;
    char in[CHUNK];
    char out[CHUNK];

    /* allocate inflate state */
    strm.zalloc = Z_NULL;
    strm.zfree = Z_NULL;
    strm.opaque = Z_NULL;
    strm.avail_in = 0;
    strm.next_in = Z_NULL;
    ret = inflateInit(&strm);
    if (ret != Z_OK)
        return ret;

```

--------------------------------

### AS400: Create ZLIB Library

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Creates a new library on the AS400 system to store ZLIB related objects. This is a prerequisite for both installation methods.

```AS400 CL
CRTLIB LIB(ZLIB) TYPE(PROD) TEXT('ZLIB compression API library')
```

--------------------------------

### zlib Compression and Decompression Example (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/examples/zlib_how.html

This C code snippet demonstrates a complete example of using zlib for file compression and decompression. It includes initialization of zlib streams, data buffering, calling deflate() and inflate() functions, handling return codes, and managing file I/O. The code is designed to be read between lines due to interspersed annotations.

```c
/* zpipe.c: example of proper use of zlib's inflate() and deflate()
   Not copyrighted -- provided to the public domain
   Version 1.2  9 November 2004  Mark Adler */

/* Version history:
   1.0  30 Oct 2004  First version
   1.1   8 Nov 2004  Add void casting for unused return values
                     Use switch statement for inflate() return values
   1.2   9 Nov 2004  Add assertions to document zlib guarantees
 */

#include <stdio.h>
#include <string.h>
#include <assert.h>
#include "zlib.h"

#define CHUNK 16384

/* Compress from file source to file dest until EOF on source.
   def() returns Z_OK on success, Z_MEM_ERROR if memory could not be
   allocated for processing, Z_STREAM_ERROR if an invalid compression
   level is supplied, Z_VERSION_ERROR if the version of zlib.h and the
   version of the library linked do not match, or Z_ERRNO if there is
   an error reading or writing the files. */
int def(FILE *source, FILE *dest, int level)
{
    int ret, flush;
    unsigned have;
    z_stream strm;
    char in[CHUNK];
    char out[CHUNK];

    strm.zalloc = Z_NULL;
    strm.zfree = Z_NULL;
    strm.opaque = Z_NULL;
    ret = deflateInit(&strm, level);
    if (ret != Z_OK)
        return ret;

    /* Process input data until EOF */
    do {
        strm.avail_in = fread(in, 1, CHUNK, source);
        if (ferror(source)) {
            (void)deflateEnd(&strm);
            return Z_ERRNO;
        }
        flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
        strm.next_in = (Bytef *)in;

        /* Run deflate() on input until output buffer is full */
        do {
            strm.avail_out = CHUNK;
            strm.next_out = (Bytef *)out;
            ret = deflate(&strm, flush);
            assert(ret != Z_STREAM_ERROR);
            have = CHUNK - strm.avail_out;
            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
                (void)deflateEnd(&strm);
                return Z_ERRNO;
            }
        } while (strm.avail_out == 0);

        /* Done when last data in file processed */
    } while (strm.avail_in != 0);

    assert(strm.next_in == in + strm.avail_in);

    /* Close the streams */
    ret = deflateEnd(&strm);
    return ret;
}

/* Decompress from file source to file dest until inflate() tells
   us we are done. */
int inf(FILE *source, FILE *dest)
{
    int ret;
    unsigned have;
    z_stream strm;
    char in[CHUNK];
    char out[CHUNK];

    /* zlib inflate initialization */
    strm.zalloc = Z_NULL;
    strm.zfree = Z_NULL;
    strm.opaque = Z_NULL;
    strm.avail_in = 0;
    strm.next_in = Z_NULL;
    ret = inflateInit(&strm);
    if (ret != Z_OK)
        return ret;

    /* Process input data until EOF */
    do {
        strm.avail_in = fread(in, 1, CHUNK, source);
        if (ferror(source)) {
            (void)inflateEnd(&strm);
            return Z_ERRNO;
        }
        if (strm.avail_in == 0)
            break;
        strm.next_in = (Bytef *)in;

        /* Run inflate() on input until output buffer is full */
        do {
            strm.avail_out = CHUNK;
            strm.next_out = (Bytef *)out;
            ret = inflate(&strm, Z_NO_FLUSH);
            assert(ret != Z_STREAM_ERROR);
            /* state not clobbered */
            if (ret == Z_DATA_ERROR) {
                (void)inflateEnd(&strm);
                return ret;
            }
            if (strm.output == CHUNK)
                break;
            have = CHUNK - strm.avail_out;
            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
                (void)inflateEnd(&strm);
                return Z_ERRNO;
            }
        } while (strm.avail_out == 0);
    } while (ret != Z_STREAM_END);

    /* Close the streams */
    ret = inflateEnd(&strm);
    return ret;
}

/* example of using the two functions above */
int main(int argc, char *argv[])
{
    FILE *source, *dest;
    char *mode;

    /* Simple command line processing */
    if (argc != 4) {
        fputs("zpipe usage: zpipe <to|from> <in> <out>\n", stderr);
        return 1;
    }

    /* Set compression/decompression mode */
    mode = argv[1];
    if (strcmp(mode, "to") == 0) {
        /* Compress file */
        source = fopen(argv[2], "rb");
        if (source == NULL) {
            perror("fopen source");
            return 1;
        }
        dest = fopen(argv[3], "wb");
        if (dest == NULL) {
            perror("fopen destination");
            fclose(source);
            return 1;
        }
        if (def(source, dest, Z_DEFAULT_COMPRESSION) != Z_OK) {
            fprintf(stderr, "zpipe: deflate failed: %s\n",
                    zError(ret));
            fclose(source);
            fclose(dest);
            return 1;
        }
        fclose(source);
        fclose(dest);
    } else if (strcmp(mode, "from") == 0) {
        /* Decompress file */
        source = fopen(argv[2], "rb");
        if (source == NULL) {
            perror("fopen source");
            return 1;
        }
        dest = fopen(argv[3], "wb");
        if (dest == NULL) {
            perror("fopen destination");
            fclose(source);
            return 1;
        }
        if (inf(source, dest) != Z_OK) {
            fprintf(stderr, "zpipe: inflate failed: %s\n",
                    zError(ret));
            fclose(source);
            fclose(dest);
            return 1;
        }
        fclose(source);
        fclose(dest);
    } else {
        fputs("Unknown mode: ", stderr);
        fputs(mode, stderr);
        fputc('\n', stderr);
        return 1;
    }

    return 0;
}

```

--------------------------------

### Perl/Tk Entry Widget Examples

Source: https://context7.com/eserte/perl-tk/llms.txt

Shows how to use the Entry widget in Perl/Tk for single-line text input. Examples include a basic entry linked to a textvariable, a password entry that masks input with asterisks, and an entry with input validation to accept only digits, demonstrating validation and invalid command callbacks.

```perl
use Tk;

my $mw = MainWindow->new(-title => 'Entry Examples');

# Simple entry with textvariable
my $name = '';
$mw->Label(-text => 'Name:')->pack(-anchor => 'w', -padx => 10);
my $name_entry = $mw->Entry(
    -textvariable => \$name,
    -width        => 30,
)->pack(-padx => 10, -pady => 5);

# Password entry (masked input)
my $password = '';
$mw->Label(-text => 'Password:')->pack(-anchor => 'w', -padx => 10);
$mw->Entry(
    -textvariable => \$password,
    -show         => '*',
    -width        => 30,
)->pack(-padx => 10, -pady => 5);

# Entry with validation
my $number = '';
$mw->Label(-text => 'Number (digits only):')->pack(-anchor => 'w', -padx => 10);
$mw->Entry(
    -textvariable    => \$number,
    -width           => 30,
    -validate        => 'key',
    -validatecommand => sub {
        my ($proposed) = @_;
        return $proposed =~ /^\d*$/;
    },
    -invalidcommand  => sub { $mw->bell },
)->pack(-padx => 10, -pady => 5);

# Submit button to demonstrate getting values
$mw->Button(
    -text    => 'Submit',
    -command => sub {
        print "Name: $name\n";
        print "Password: $password\n";
        print "Number: $number\n";
    },
)->pack(-pady => 10);


```

--------------------------------

### PNG Image Information Setup

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Functions for setting essential image metadata before writing a PNG file.

```APIDOC
## PNG Image Information Setup

### Description
Functions to populate the `png_info` structure with image metadata required for writing a PNG file. This includes image dimensions, color properties, and optional metadata chunks.

### Method
Various (internal libpng functions)

### Endpoints
N/A (Internal functions)

### Parameters
#### `png_set_IHDR`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`width`** (png_uint_32) - Width of the image in pixels (up to 2^31).
- **`height`** (png_uint_32) - Height of the image in pixels (up to 2^31).
- **`bit_depth`** (int) - Bit depth of one channel (1, 2, 4, 8, 16, depending on `color_type`).
- **`color_type`** (int) - Describes color/alpha channels present (e.g., `PNG_COLOR_TYPE_GRAY`, `PNG_COLOR_TYPE_RGB_ALPHA`).
- **`interlace_type`** (int) - Interlace method (`PNG_INTERLACE_NONE` or `PNG_INTERLACE_ADAM7`).
- **`compression_type`** (int) - Compression method (must be `PNG_COMPRESSION_TYPE_DEFAULT`).
- **`filter_method`** (int) - Filter method (`PNG_FILTER_TYPE_DEFAULT` or `PNG_INTRAPIXEL_DIFFERENCING`).

#### `png_set_PLTE`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`palette`** (png_colorp) - Array of `png_color` structures representing the palette.
- **`num_palette`** (int) - Number of entries in the palette.

#### `png_set_gAMA`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`gamma`** (double) - The gamma value the image was created at.

#### `png_set_sRGB`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`srgb_intent`** (int) - The sRGB rendering intent (e.g., `PNG_sRGB_INTENT_PERCEPTUAL`).

#### `png_set_sRGB_gAMA_and_cHRM`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`srgb_intent`** (int) - The sRGB rendering intent.

#### `png_set_iCCP`
- **`png_ptr`** (png_structp) - Pointer to the png structure.
- **`info_ptr`** (png_infop) - Pointer to the info structure.
- **`name`** (char *) - The profile name.
- **`compression_type`** (int) - The compression type (always `PNG_COMPRESSION_TYPE_BASE` for PNG 1.0).
- **`profile`** (png_bytep) - The ICC profile data.
- **`proflen`** (png_uint_32) - The length of the profile data.

### Request Example
```c
png_set_IHDR(png_ptr, info_ptr, width, height, bit_depth, color_type, PNG_INTERLACE_NONE, PNG_COMPRESSION_TYPE_DEFAULT, PNG_FILTER_TYPE_DEFAULT);
png_set_PLTE(png_ptr, info_ptr, palette, num_palette);
png_set_gAMA(png_ptr, info_ptr, gamma);
png_set_sRGB(png_ptr, info_ptr, PNG_sRGB_INTENT_PERCEPTUAL);
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, PNG_sRGB_INTENT_PERCEPTUAL);
png_set_iCCP(png_ptr, info_ptr, "MyProfile", PNG_COMPRESSION_TYPE_BASE, profile_data, profile_length);
```

### Response
#### Success Response (void)
These functions do not return a value upon success.

#### Response Example
N/A
```

--------------------------------

### AS400: Create Save File

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Creates a save file on the AS400 system, used to store ZLIB objects when installing from a SAVF file. This file will later be populated with ZLIB components.

```AS400 CL
CRTSAVF FILE(ZLIB/ZLIBSAVF)
```

--------------------------------

### AS400: Create Source Physical Files

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Creates source physical files on the AS400 system to hold ZLIB source code and related utilities. These files are used when installing from the original source distribution.

```AS400 CL
CRTSRCPF FILE(ZLIB/SOURCES) RCDLEN(112) TEXT('ZLIB library modules')
```

```AS400 CL
CRTSRCPF FILE(ZLIB/H)       RCDLEN(112) TEXT('ZLIB library includes')
```

```AS400 CL
CRTSRCPF FILE(ZLIB/TOOLS)   RCDLEN(112) TEXT('ZLIB library control utilities')
```

--------------------------------

### AS400: Execute CL Program

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Calls a Control Language (CL) program on the AS400. This is used to execute the compiled ZLIB installation and build utilities.

```AS400 CL
CALL PGM(ZLIB/COMPILE)
```

--------------------------------

### Interlace Handling Setup

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

This section describes how to configure libpng to handle interlaced PNG images using the Adam7 interlacing method. It involves calling `png_set_interlace_handling` before reading image data.

```APIDOC
## Interlace Handling Setup

### Description
Configures libpng to handle interlaced PNG images using the Adam7 interlacing method. This function should be called before `png_start_read_image()` or `png_read_update_info()`.

### Method
`png_set_interlace_handling(png_ptr)`

### Parameters
- **png_ptr** (*pointer*) - Required - Pointer to the png_struct structure.

### Returns
- **number_of_passes** (*integer*) - The number of passes needed for interlacing. Currently, this is always seven for Adam7, but may change in the future. Returns one if the file is not interlaced.

### Request Example
```c
if (interlace_type == PNG_INTERLACE_ADAM7)
    number_of_passes = png_set_interlace_handling(png_ptr);
```

### Response
#### Success Response (200)
- **number_of_passes** (*integer*) - The number of interlacing passes.

#### Response Example
```json
{
  "number_of_passes": 7
}
```
```

--------------------------------

### Main Routine for Compression/Decompression (Perl)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/examples/zlib_how.html

The main() routine handles command-line arguments to perform compression or decompression from stdin to stdout. It defaults to compression, supports decompression with '-d', and displays a usage message for invalid arguments.

```Perl
int main(int argc, char **argv)
{
    int ret;

    /* do compression if no arguments */
    if (argc == 1) {
        ret = def(stdin, stdout, Z_DEFAULT_COMPRESSION);
        if (ret != Z_OK)
            zerr(ret);
        return ret;
    }

    /* do decompression if -d specified */
    else if (argc == 2 && strcmp(argv[1], "-d") == 0) {
        ret = inf(stdin, stdout);
        if (ret != Z_OK)
            zerr(ret);
        return ret;
    }

    /* otherwise, report usage */
    else {
        fputs("zpipe usage: zpipe [-d] < source > dest\n", stderr);
        return 1;
    }
}
```

--------------------------------

### Example of Transferring Data Freering Responsibility

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Demonstrates how to transfer data freeing responsibility from a read structure to a write structure using png_data_freer. This allows data like palettes and text chunks to be safely reused.

```c
png_data_freer(read_ptr, read_info_ptr,
       PNG_USER_WILL_FREE_DATA,
       PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
png_data_freer(write_ptr, write_info_ptr,
       PNG_DESTROY_WILL_FREE_DATA,
       PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
```

--------------------------------

### Create and Display Images in Perl Tk

Source: https://context7.com/eserte/perl-tk/llms.txt

Demonstrates how to create image objects, draw patterns on them, and display them as labels or within buttons. It also shows how to get image dimensions and copy images.

```perl
my $checker = $mw->Photo(-width => 80, -height => 80);
for my $row (0..7) {
    for my $col (0..7) {
        my $color = (($row + $col) % 2) ? 'white' : 'black';
        $checker->put($color, -to => $col*10, $row*10, ($col+1)*10, ($row+1)*10);
    }
}

$mw->Label(
    -image => $checker,
    -relief => 'raised',
)->pack(-pady => 10);

# Button with image
my $btn_image = $mw->Photo(-width => 20, -height => 20);
$btn_image->put('green', -to => 0, 0, 20, 20);
$btn_image->put('darkgreen', -to => 5, 5, 15, 15);

$mw->Button(
    -image   => $btn_image,
    -command => sub { print "Image button clicked\n" },
)->pack(-pady => 10);

# Canvas with image
my $canvas = $mw->Canvas(-width => 200, -height => 150, -background => 'gray')->pack(-pady => 10);
$canvas->createImage(100, 75, -image => $photo);

# Image manipulation buttons
my $btn_frame = $mw->Frame->pack(-pady => 5);

$btn_frame->Button(
    -text    => 'Get Size',
    -command => sub {
        my $w = $photo->width;
        my $h = $photo->height;
        print "Image size: ${w}x${h}\n";
    },
)->pack(-side => 'left', -padx => 2);

$btn_frame->Button(
    -text    => 'Copy',
    -command => sub {
        my $copy = $mw->Photo;
        $copy->copy($photo);
        print "Image copied\n";
    },
)->pack(-side => 'left', -padx => 2);

MainLoop;
```

--------------------------------

### AS400: Restore Objects from Save File

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Restores all objects from a specified save file into a target library on the AS400. This command is used after uploading a SAVF file containing ZLIB components.

```AS400 CL
RSTOBJ OBJ(*ALL) SAVLIB(ZLIB) DEV(*SAVF) SAVF(ZLIB/ZLIBSAVF) RSTLIB(ZLIB)
```

--------------------------------

### Input/Output Initialization

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Configure how libpng reads PNG data. You can use the default `fread()` function or implement custom I/O methods.

```APIDOC
## Input/Output Initialization

### Description
This section covers setting up the input source for libpng. By default, libpng uses the C standard library's `fread()` function. If you choose to use `fread()`, you must provide a valid `FILE*` pointer opened in binary mode to `png_init_io()`.

Alternatively, you can implement custom I/O methods by not calling `png_init_io()` and instead providing your own I/O routines as described in the 'Customizing Libpng' section.

### Method
`png_init_io(png_ptr, fp)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
png_init_io(png_ptr, fp);
```

### Response
#### Success Response (200)
N/A (This is a function call, not an API endpoint with a direct response)

#### Response Example
N/A
```

--------------------------------

### Get libpng Version Number at Runtime

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the libpng library version number at runtime. The returned number is encoded as major version, minor version (with leading zero), and release number (with leading zero). For example, version 1.0.7 is represented as 10007.

```c
png_uint_32 libpng_vn = png_access_version_number();
```

--------------------------------

### Libpng Initialization and Destruction Functions

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Details on preferred methods for creating and initializing libpng structures, and functions for cleaning up resources.

```APIDOC
## Initialization and Destruction Functions

### Description
This section details the preferred functions for initializing libpng structures and cleaning up allocated resources. It also discusses older functions that have been deprecated or moved to internal use.

### Method
Various (primarily C functions)

### Endpoint
N/A (Library Functions)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
// Example of using preferred initialization functions
png_structp png_ptr = png_create_read_struct(PNG_LIBPNG_VER, NULL, NULL, NULL);
png_infop info_ptr = png_create_info_struct(png_ptr);
// ... image reading logic ...
png_destroy_read_struct(&png_ptr, &info_ptr, NULL);
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A

### Notes
- `png_info_init()`, `png_read_destroy()`, and `png_write_destroy()` are deprecated and moved to `PNG_INTERNAL` since version 0.95. They will be removed in version 2.0.0.
- Preferred initialization functions: `png_create_read_struct()`, `png_create_write_struct()`, `png_create_info_struct()`.
- `png_read_destroy()` and `png_write_destroy()` reset data structures but do not free allocated memory. `png_destroy_read_struct()` and `png_destroy_write_struct()` should be used for full cleanup.
- Setting error callbacks via `png_set_message_fn()` before `png_read_init()` is no longer supported since version 0.88.
- Error callbacks can be set after `png_read_init()` or changed using `png_set_error_fn()`.
```

--------------------------------

### AS400: Compile CL Program

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/as400/readme.txt

Compiles a Control Language (CL) program member on the AS400. This is used to compile the ZLIB installation and build utilities.

```AS400 CL
CRTCLPGM PGM(ZLIB/COMPILE) SRCFILE(ZLIB/TOOLS) SRCMBR(COMPILE)
```

--------------------------------

### Initialize Progressive PNG Reader (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

This C code snippet demonstrates the initialization of libpng for progressive reading. It involves creating the read and info structures, setting up jump buffers for error handling, and crucially, calling png_set_progressive_read_fn to register callback functions for handling image info, rows, and end-of-image events.

```c
png_structp png_ptr;
png_infop info_ptr;

// Assume user_error_ptr, user_error_fn, user_warning_fn are defined

int initialize_png_reader() {
    png_ptr = png_create_read_struct(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, user_error_fn, user_warning_fn);
    if (!png_ptr) return (ERROR);

    info_ptr = png_create_info_struct(png_ptr);
    if (!info_ptr) {
        png_destroy_read_struct(&png_ptr, (png_infopp)NULL, (png_infopp)NULL);
        return (ERROR);
    }

    if (setjmp(png_jmpbuf(png_ptr))) {
        png_destroy_read_struct(&png_ptr, &info_ptr, (png_infopp)NULL);
        return (ERROR);
    }

    // Register callbacks for progressive reading
    png_set_progressive_read_fn(png_ptr, (png_voidp)user_ptr, NULL, NULL, NULL);

    return (SUCCESS);
}
```

--------------------------------

### Initialize PNG Write Structure (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Allocates and initializes the necessary structures for writing a PNG file. This includes the png_struct and png_info structures. It's recommended to perform I/O initialization before this step and check for NULL return values.

```c
png_structp png_ptr = png_create_write_struct

```

--------------------------------

### Input/Output Callbacks

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Libpng provides flexibility in handling input and output operations by allowing users to set custom read, write, and flush functions.

```APIDOC
## Input/Output Callbacks

### Description
Customize how libpng reads from and writes to data sources.

### Method
Use `png_set_read_fn()` and `png_set_write_fn()` to register custom I/O functions.

### Endpoint
N/A (Function registration)

### Parameters
#### `png_set_read_fn`
- **read_ptr** (png_structp) - Required - Pointer to the PNG read structure.
- **read_io_ptr** (voidp) - Optional - A user-defined pointer to be passed to the read function.
- **read_data_fn** (png_rw_ptr) - Optional - Function pointer for reading data. If NULL, default C stream functions are used.

#### `png_set_write_fn`
- **write_ptr** (png_structp) - Required - Pointer to the PNG write structure.
- **write_io_ptr** (voidp) - Optional - A user-defined pointer to be passed to the write function.
- **write_data_fn** (png_rw_ptr) - Optional - Function pointer for writing data. If NULL, default C stream functions are used.
- **output_flush_fn** (png_flush_ptr) - Optional - Function pointer for flushing output buffers.

### Request Example
```c
voidp my_io_ptr = malloc(sizeof(MyIOContext));
png_set_read_fn(png_ptr, my_io_ptr, my_read_data_callback);
png_set_write_fn(png_ptr, my_io_ptr, my_write_data_callback, my_flush_callback);
```

### Response
#### Success Response (Function registration)
(N/A - success is indicated by the absence of errors)

#### Response Example
(N/A)

### Retrieving I/O Pointer
- **Function**: `png_get_io_ptr(png_structp png_ptr)`
- **Description**: Retrieves the `void *` pointer associated with the I/O callbacks.
- **Return Value**: `voidp` - The user-defined pointer.

### Callback Function Prototypes
```c
void user_read_data(png_structp png_ptr, png_bytep data, png_size_t length);
void user_write_data(png_structp png_ptr, png_bytep data, png_size_t length);
void user_flush_data(png_structp png_ptr);
```
```

--------------------------------

### Initialize PNG I/O with File Pointer

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Configures libpng to use the standard C fread() function for reading PNG data. Requires a valid FILE pointer opened in binary mode.

```c
png_init_io(png_ptr, fp);
```

--------------------------------

### Initialize libpng Read Structure

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Creates and initializes a libpng read structure. This is the preferred method over older functions like png_info_init() as it allows for version checking and custom error handling during initialization.

```c
png_structp png_ptr = png_create_read_struct(PNG_LIBPNG_VER, NULL, NULL, NULL);
```

--------------------------------

### Initialize libpng Info Structure

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Creates and initializes a libpng info structure, which holds PNG metadata. This function is part of the preferred initialization sequence for libpng.

```c
png_infop info_ptr = png_create_info_struct(png_ptr);
```

--------------------------------

### Get PNG Modification Time

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the last modification time of the PNG file. This is stored as a tIME chunk within the PNG data.

```c
png_timep mod_time;

if (png_get_tIME(png_ptr, info_ptr, &mod_time)) {
    // Modification time is available
}
```

--------------------------------

### Get PNG Histogram Data

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves histogram data for the palette entries in a PNG image. This provides information about the frequency of each color in the palette.

```c
png_uint_16p hist;

if (png_get_hIST(png_ptr, info_ptr, &hist)) {
    // Histogram data is available
}
```

--------------------------------

### Get PNG Interlace Type

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Determines the interlace type of a PNG image. This indicates whether the image uses Adam7 interlacing or no interlacing.

```c
int interlace_type;

interlace_type = png_get_interlace_type(png_ptr, info_ptr);
```

--------------------------------

### Get User Transform Pointer

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the pointer to the user structure set via png_set_user_transform_info(). This allows the callback function to access user-defined data.

```c
voidp write_user_transform_ptr = png_get_user_transform_ptr(png_ptr);
```

--------------------------------

### Run inflate() Until Output Buffer Not Full (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/examples/zlib_how.html

This C code demonstrates the inner loop for the inflate function, repeatedly calling inflate() until the output buffer is no longer full. It manages the output buffer size and checks for decompression errors.

```c
do {
    strm.avail_out = CHUNK;
    strm.next_out = out;
    ret = inflate(&strm, Z_NO_FLUSH);
    assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
    switch (ret) {
    case Z_NEED_DICT:
        ret = Z_DATA_ERROR;     /* and fall through */
    case Z_DATA_ERROR:
    case Z_MEM_ERROR:
        (void)inflateEnd(&strm);
        return ret;
    }
    have = CHUNK - strm.avail_out;
    if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
        (void)inflateEnd(&strm);
        return Z_ERRNO;
    }
} while (strm.avail_out == 0);
```

--------------------------------

### Initialize libpng Read Structures

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

This code snippet demonstrates the initialization of libpng's core structures, `png_struct` and `png_info`, for reading PNG files. It includes error checking for structure allocation failures and proper cleanup using `png_destroy_read_struct` in case of errors. Optional user-defined error handling functions can be provided.

```c
png_structp png_ptr = png_create_read_struct
       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
        user_error_fn, user_warning_fn);
    if (!png_ptr)
        return (ERROR);

    png_infop info_ptr = png_create_info_struct(png_ptr);
    if (!info_ptr)
    {
        png_destroy_read_struct(&png_ptr,
           (png_infopp)NULL, (png_infopp)NULL);
        return (ERROR);
    }

    png_infop end_info = png_create_info_struct(png_ptr);
    if (!end_info)
    {
        png_destroy_read_struct(&png_ptr, &info_ptr,
          (png_infopp)NULL);
        return (ERROR);
    }
```

--------------------------------

### Get PNG Offset (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the offset information from the oFFs chunk of a PNG file. This indicates the position of the image relative to the screen edges.

```c
png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
       &unit_type);
```

--------------------------------

### Create Perl/Tk Application Root (MainWindow)

Source: https://context7.com/eserte/perl-tk/llms.txt

Demonstrates how to create the main application window (MainWindow) in Perl/Tk. This is the root container for all other widgets. It sets the window title, size, and minimum/maximum dimensions, and includes basic Label and Button widgets before entering the main event loop.

```perl
#!/usr/bin/perl
use strict;
use warnings;
use Tk;

# Create the main application window
my $mw = MainWindow->new(
    -title      => 'My Application',
    -background => '#f0f0f0',
);

# Set window size and position
$mw->geometry('400x300+100+100');

# Configure window properties
$mw->minsize(300, 200);
$mw->maxsize(800, 600);

# Add widgets to the main window
$mw->Label(-text => 'Welcome to Perl/Tk!')->pack(-pady => 20);

$mw->Button(
    -text    => 'Quit',
    -command => sub { exit },
)->pack;

# Enter the main event loop
MainLoop;

```

--------------------------------

### Get PNG Palette Information

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the color palette and the number of entries in it for a paletted PNG image. This is essential for rendering indexed color images.

```c
png_colorp palette;
png_uint_32 num_palette;

if (png_get_PLTE(png_ptr, info_ptr, &palette, &num_palette)) {
    // Palette data is available
}
```

--------------------------------

### Get PNG Compression and Filter Method

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the compression and filter method used in a PNG file. These are crucial for decompression and understanding the data encoding.

```c
png_byte compression_type, filter_method;

compression_type = png_get_compression_type(png_ptr, info_ptr);
filter_method = png_get_filter_type(png_ptr, info_ptr);
```

--------------------------------

### Get PNG Row Bytes

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Calculates the number of bytes required to store a single row of pixel data for the PNG image. This is useful for memory allocation.

```c
png_size_t rowbytes;

rowbytes = png_get_rowbytes(png_ptr, info_ptr);
```

--------------------------------

### Get PNG Image Dimensions

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the width and height of a PNG image using libpng functions. These functions require valid png_ptr and info_ptr arguments.

```c
png_uint_32 width, height;

width = png_get_image_width(png_ptr, info_ptr);
height = png_get_image_height(png_ptr, info_ptr);
```

--------------------------------

### Initialize PNG Write Structure (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Initializes the libpng structure for writing PNG data. It requires version information, user error handling pointers, and optionally user memory allocation routines. Returns a pointer to the initialized structure or NULL on failure.

```c
png_structp png_ptr = png_create_write_struct(
    PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
    user_error_fn, user_warning_fn);
if (!png_ptr)
   return (ERROR);
```

```c
png_structp png_ptr = png_create_write_struct_2
   (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
    user_error_fn, user_warning_fn, (png_voidp)
    user_mem_ptr, user_malloc_fn, user_free_fn);
```

--------------------------------

### Get PNG Transparency Information

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves transparency information for the PNG image. This includes transparency values for paletted images and a single transparent color for non-paletted images.

```c
png_bytep trans = NULL;
png_uint_32 num_trans = 0;
png_color_16p trans_values = NULL;

if (png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans, &trans_values)) {
    // Transparency data is available
}
```

--------------------------------

### Perl/Tk Button Widget Examples

Source: https://context7.com/eserte/perl-tk/llms.txt

Illustrates the creation and configuration of Button widgets in Perl/Tk. This includes simple text buttons with callbacks, styled buttons with custom colors and dimensions, buttons that update text based on a counter, disabled buttons, and buttons displaying images.

```perl
use Tk;

my $mw = MainWindow->new(-title => 'Button Examples');

# Simple text button with callback
$mw->Button(
    -text    => 'Click Me',
    -command => sub { print "Button clicked!\n" },
)->pack(-pady => 5);

# Button with width and color options
$mw->Button(
    -text       => 'Styled Button',
    -width      => 20,
    -background => '#4a90d9',
    -foreground => 'white',
    -activebackground => '#357abd',
    -command    => sub { print "Styled button pressed\n" },
)->pack(-pady => 5);

# Button with callback and arguments
my $count = 0;
my $counter_btn = $mw->Button(
    -text    => "Count: 0",
    -command => sub {
        $count++;
        $counter_btn->configure(-text => "Count: $count");
    },
)->pack(-pady => 5);

# Disabled button
$mw->Button(
    -text  => 'Disabled',
    -state => 'disabled',
)->pack(-pady => 5);

# Button with image
my $photo = $mw->Photo(-file => 'icon.gif') if -e 'icon.gif';
$mw->Button(
    -image   => $photo,
    -command => sub { print "Image button clicked\n" },
)->pack(-pady => 5) if $photo;

MainLoop;

```

--------------------------------

### Get PNG sRGB Intent

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the sRGB rendering intent for the PNG image. The presence of this chunk indicates that the image data conforms to the sRGB color space.

```c
int srgb_intent;

if (png_get_sRGB(png_ptr, info_ptr, &srgb_intent)) {
    // sRGB information is available
}
```

--------------------------------

### Configure libpng Compression Settings

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

These functions allow fine-grained control over the zlib compression used by libpng. They configure memory levels, strategies, window bits, and methods. Incorrect usage may lead to invalid PNG files. Refer to zlib.h for detailed parameter meanings.

```c
png_set_compression_mem_level(png_ptr, level);
png_set_compression_strategy(png_ptr,
    strategy);
png_set_compression_window_bits(png_ptr,
    window_bits);
png_set_compression_method(png_ptr, method);
png_set_compression_buffer_size(png_ptr, size);
```

--------------------------------

### Get PNG Gamma Correction

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the gamma correction value associated with the PNG image. This information is used for accurate color rendering across different displays.

```c
double gamma;

if (png_get_gAMA(png_ptr, info_ptr, &gamma)) {
    // Gamma value is available
}
```

--------------------------------

### Initialize libpng Read Structures with Custom Memory Allocation

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

This C code shows how to initialize libpng's read structures using custom memory allocation routines. It requires defining `PNG_USER_MEM_SUPPORTED` and using `png_create_read_struct_2`, passing pointers to user-defined memory allocation and deallocation functions.

```c
png_structp png_ptr = png_create_read_struct_2
       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
        user_error_fn, user_warning_fn, (png_voidp)
        user_mem_ptr, user_malloc_fn, user_free_fn);
```

--------------------------------

### Get PNG Signature

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the PNG signature from the file, if available. The signature is used to identify the file as a PNG. The data is offset if part of the signature was read previously.

```c
png_bytep signature;

signature = png_get_signature(png_ptr, info_ptr);
```

--------------------------------

### Get PNG Channel Count

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Returns the number of channels per pixel for the PNG image's color type. This helps in understanding the pixel data structure.

```c
png_byte channels;

channels = png_get_channels(png_ptr, info_ptr);
```

--------------------------------

### Calculating Deflate Output and Writing to File

Source: https://github.com/eserte/perl-tk/blob/master/PNG/zlib/examples/zlib_how.html

This code calculates the amount of data produced by the deflate() function on the last call by comparing the available output buffer space before and after the call. It then writes this compressed data to the destination file and handles potential file I/O errors by cleaning up the compression stream.

```c
have = CHUNK - strm.avail_out;
if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
    (void)deflateEnd(&strm);
    return Z_ERRNO;
}
```

--------------------------------

### Get PNG Pixel Aspect Ratio (C)

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Retrieves the aspect ratio of a pixel from the pHYs chunk of a PNG file. This is useful for correctly displaying images with non-square pixels.

```c
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
       info_ptr);
```

--------------------------------

### Initialize libpng Write Structure

Source: https://github.com/eserte/perl-tk/blob/master/PNG/libpng/libpng.txt

Creates and initializes a libpng write structure. This function is recommended for initializing structures used for writing PNG files, offering benefits like version checking and custom error handling.

```c
png_structp png_ptr = png_create_write_struct(PNG_LIBPNG_VER, NULL, NULL, NULL);
```