pix1.c

Go to the documentation of this file.

/*====================================================================*
 -  Copyright (C) 2001 Leptonica.  All rights reserved.
 -
 -  Redistribution and use in source and binary forms, with or without
 -  modification, are permitted provided that the following conditions
 -  are met:
 -  1. Redistributions of source code must retain the above copyright
 -     notice, this list of conditions and the following disclaimer.
 -  2. Redistributions in binary form must reproduce the above
 -     copyright notice, this list of conditions and the following
 -     disclaimer in the documentation and/or other materials
 -     provided with the distribution.
 -
 -  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 -  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 -  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 -  A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ANY
 -  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 -  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 -  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 -  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 -  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 -  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 -  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *====================================================================*/
 
#ifdef HAVE_CONFIG_H
#include <config_auto.h>
#endif  /* HAVE_CONFIG_H */
 
#include <string.h>
#include "allheaders.h"
#include "pix_internal.h"
 
static void pixFree(PIX *pix);
 
/*-------------------------------------------------------------------------*
 *                        Pix Memory Management                            *
 *                                                                         *
 *  These functions give you the freedom to specify at compile or run      *
 *  time the allocator and deallocator to be used for the pix raster       *
 *  image data.  They have no effect on any other heap allocation,         *
 *  including the pix struct itself, which is controlled by the            *
 *  #defines in environ.h.                                                 *
 *                                                                         *
 *  The default functions for allocating pix raster data are malloc and    *
 *  free (or leptonica_* custom allocators if LEPTONICA_INTERCEPT_ALLOC    *
 *  is defined).  Use setPixMemoryManager() to specify other functions     *
 *  to use specifically for pix raster image data.                         *
 *-------------------------------------------------------------------------*/
    /*
     * <pre>
     * Notes:
     *      (1) The allocator and deallocator function types,
     *          alloc_fn and dealloc_fn, are defined in pix.h.
     * </pre>
     */
struct PixMemoryManager
{
    alloc_fn    allocator;
    dealloc_fn  deallocator;
};
 
static struct PixMemoryManager  pix_mem_manager = {
#ifdef LEPTONICA_INTERCEPT_ALLOC
    &leptonica_malloc,
    &leptonica_free
#else
    &malloc,
    &free
#endif  /* LEPTONICA_INTERCEPT_ALLOC */
};
 
static void *
pixdata_malloc(size_t  size)
{
#ifndef _MSC_VER
    return (*pix_mem_manager.allocator)(size);
#else  /* _MSC_VER */
    /* Under MSVC++, pix_mem_manager is initialized after a call to
     * pixdata_malloc.  Just ignore the custom allocator feature. */
    return LEPT_MALLOC(size);
#endif  /* _MSC_VER */
}
 
static void
pixdata_free(void  *ptr)
{
#ifndef _MSC_VER
    (*pix_mem_manager.deallocator)(ptr);
#else  /* _MSC_VER */
    /* Under MSVC++, pix_mem_manager is initialized after a call to
     * pixdata_malloc.  Just ignore the custom allocator feature. */
    LEPT_FREE(ptr);
#endif  /* _MSC_VER */
}
 
void
setPixMemoryManager(alloc_fn   allocator,
                    dealloc_fn deallocator)
{
    if (allocator) pix_mem_manager.allocator = allocator;
    if (deallocator) pix_mem_manager.deallocator = deallocator;
}
 
 
/*--------------------------------------------------------------------*
 *                             Pix Creation                           *
 *--------------------------------------------------------------------*/
PIX *
pixCreate(l_int32  width,
          l_int32  height,
          l_int32  depth)
{
PIX  *pixd;
 
    if ((pixd = pixCreateNoInit(width, height, depth)) == NULL)
        return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
    memset(pixd->data, 0, 4LL * pixd->wpl * pixd->h);
    return pixd;
}
 
 
PIX *
pixCreateNoInit(l_int32  width,
                l_int32  height,
                l_int32  depth)
{
l_int32    wpl;
PIX       *pixd;
l_uint32  *data;
 
    if ((pixd = pixCreateHeader(width, height, depth)) == NULL)
        return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
    wpl = pixGetWpl(pixd);
    if ((data = (l_uint32 *)pixdata_malloc(4LL * wpl * height)) == NULL) {
        pixDestroy(&pixd);
        return (PIX *)ERROR_PTR("pixdata_malloc fail for data",
                                __func__, NULL);
    }
    pixSetData(pixd, data);
    pixSetPadBits(pixd, 0);
    return pixd;
}
 
 
PIX *
pixCreateTemplate(const PIX  *pixs)
{
PIX  *pixd;
 
    if (!pixs)
        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);
 
    if ((pixd = pixCreateTemplateNoInit(pixs)) == NULL)
        return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
    memset(pixd->data, 0, 4LL * pixd->wpl * pixd->h);
    return pixd;
}
 
 
PIX *
pixCreateTemplateNoInit(const PIX  *pixs)
{
l_int32  w, h, d;
PIX     *pixd;
 
    if (!pixs)
        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);
 
    pixGetDimensions(pixs, &w, &h, &d);
    if ((pixd = pixCreateNoInit(w, h, d)) == NULL)
        return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
    pixCopySpp(pixd, pixs);
    pixCopyResolution(pixd, pixs);
    pixCopyColormap(pixd, pixs);
    pixCopyText(pixd, pixs);
    pixCopyInputFormat(pixd, pixs);
    pixSetPadBits(pixd, 0);
    return pixd;
}
 
 
PIX *
pixCreateWithCmap(l_int32  width,
                 l_int32  height,
                 l_int32  depth,
                 l_int32  initcolor)
{
PIX       *pix;
PIXCMAP   *cmap;
 
    if (depth != 2 && depth != 4 && depth != 8)
        return (PIX *)ERROR_PTR("depth not 2, 4 or 8 bpp", __func__, NULL);
 
    if ((pix = pixCreate(width, height, depth)) == NULL)
        return (PIX *)ERROR_PTR("pix not made", __func__, NULL);
    cmap = pixcmapCreate(depth);
    pixSetColormap(pix, cmap);
    if (initcolor == L_SET_BLACK)
         pixcmapAddColor(cmap, 0, 0, 0);
    else  /* L_SET_WHITE */
         pixcmapAddColor(cmap, 255, 255, 255);
    return pix;
}
 
 
PIX *
pixCreateHeader(l_int32  width,
                l_int32  height,
                l_int32  depth)
{
l_int32   wpl;
l_uint64  wpl64, bignum;
PIX      *pixd;
 
    if ((depth != 1) && (depth != 2) && (depth != 4) && (depth != 8)
         && (depth != 16) && (depth != 24) && (depth != 32))
        return (PIX *)ERROR_PTR("depth must be {1, 2, 4, 8, 16, 24, 32}",
                                __func__, NULL);
    if (width <= 0)
        return (PIX *)ERROR_PTR("width must be > 0", __func__, NULL);
    if (height <= 0)
        return (PIX *)ERROR_PTR("height must be > 0", __func__, NULL);
 
        /* Avoid overflow in malloc, malicious or otherwise */
    wpl64 = ((l_uint64)width * (l_uint64)depth + 31) / 32;
    if (wpl64 > ((1LL << 24) - 1)) {
        L_ERROR("requested w = %d, h = %d, d = %d\n",
                __func__, width, height, depth);
        return (PIX *)ERROR_PTR("wpl >= 2^24", __func__, NULL);
    }
    wpl = (l_int32)wpl64;
    bignum = 4LL * wpl * height;   /* number of bytes to be requested */
    if (bignum > ((1LL << 31) - 1)) {
        L_ERROR("requested w = %d, h = %d, d = %d\n",
                __func__, width, height, depth);
        return (PIX *)ERROR_PTR("requested bytes >= 2^31", __func__, NULL);
    }
 
#ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION
    if (bignum > (1LL << 26)) {
        L_ERROR("fuzzer requested > 64 MB; refused\n", __func__);
        return NULL;
    }
    if (width > 20000) {
        L_ERROR("fuzzer requested width > 20K; refused\n", __func__);
        return NULL;
    }
    if (height > 20000) {
        L_ERROR("fuzzer requested height > 20K; refused\n", __func__);
        return NULL;
    }
#endif   /* FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION */
 
    if ((pixd = (PIX *)LEPT_CALLOC(1, sizeof(PIX))) == NULL)
        return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
    pixSetWidth(pixd, width);
    pixSetHeight(pixd, height);
    pixSetDepth(pixd, depth);
    pixSetWpl(pixd, wpl);
    if (depth == 24 || depth == 32)
        pixSetSpp(pixd, 3);
    else
        pixSetSpp(pixd, 1);
    pixd->refcount = 1;
    pixd->informat = IFF_UNKNOWN;
    return pixd;
}
 
 
PIX *
pixClone(PIX  *pixs)
{
    if (!pixs)
        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);
    ++pixs->refcount;
 
    return pixs;
}
 
 
/*--------------------------------------------------------------------*
 *                           Pix Destruction                          *
 *--------------------------------------------------------------------*/
void
pixDestroy(PIX  **ppix)
{
PIX  *pix;
 
    if (!ppix) {
        L_WARNING("ptr address is null!\n", __func__);
        return;
    }
 
    if ((pix = *ppix) == NULL)
        return;
    pixFree(pix);
    *ppix = NULL;
}
 
 
static void
pixFree(PIX  *pix)
{
l_uint32  *data;
char      *text;
 
    if (!pix) return;
 
    if (--pix->refcount == 0) {
        if ((data = pixGetData(pix)) != NULL)
            pixdata_free(data);
        if ((text = pixGetText(pix)) != NULL)
            LEPT_FREE(text);
        pixDestroyColormap(pix);
        LEPT_FREE(pix);
    }
    return;
}
 
 
/*-------------------------------------------------------------------------*
 *                                 Pix Copy                                *
 *-------------------------------------------------------------------------*/
PIX *
pixCopy(PIX        *pixd,   /* can be null */
        const PIX  *pixs)
{
l_int32  bytes;
 
    if (!pixs)
        return (PIX *)ERROR_PTR("pixs not defined", __func__, pixd);
    if (pixs == pixd)
        return pixd;
 
        /* Total bytes in image data */
    bytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
 
        /* If we're making a new pix ... */
    if (!pixd) {
        if ((pixd = pixCreateTemplate(pixs)) == NULL)
            return (PIX *)ERROR_PTR("pixd not made", __func__, NULL);
        memcpy(pixd->data, pixs->data, bytes);
        return pixd;
    }
 
        /* Reallocate image data if sizes are different.  If this fails,
         * pixd hasn't been changed.  But we want to signal that the copy
         * failed, so return NULL.  This will cause a memory leak if the
         * return ptr is assigned to pixd, but that is preferred to proceeding
         * with an incorrect pixd, and in any event this use case of
         * pixCopy() -- reallocating into an existing pix -- is infrequent.  */
    if (pixResizeImageData(pixd, pixs) == 1)
        return (PIX *)ERROR_PTR("reallocation of data failed", __func__, NULL);
 
        /* Copy non-image data fields */
    pixCopyColormap(pixd, pixs);
    pixCopySpp(pixd, pixs);
    pixCopyResolution(pixd, pixs);
    pixCopyInputFormat(pixd, pixs);
    pixCopyText(pixd, pixs);
 
        /* Copy image data */
    memcpy(pixd->data, pixs->data, bytes);
    return pixd;
}
 
 
l_ok
pixResizeImageData(PIX        *pixd,
                   const PIX  *pixs)
{
l_int32    w, h, d, wpl, bytes;
l_uint32  *data;
 
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
 
    if (pixSizesEqual(pixs, pixd))  /* nothing to do */
        return 0;
 
        /* Make sure we can copy the data */
    pixGetDimensions(pixs, &w, &h, &d);
    wpl = pixGetWpl(pixs);
    bytes = 4 * wpl * h;
    if ((data = (l_uint32 *)pixdata_malloc(bytes)) == NULL)
        return ERROR_INT("pixdata_malloc fail for data", __func__, 1);
 
        /* OK, do it */
    pixSetWidth(pixd, w);
    pixSetHeight(pixd, h);
    pixSetDepth(pixd, d);
    pixSetWpl(pixd, wpl);
    pixFreeAndSetData(pixd, data);  /* free old data and assign new data */
    pixCopyResolution(pixd, pixs);
    return 0;
}
 
 
l_ok
pixCopyColormap(PIX        *pixd,
                const PIX  *pixs)
{
l_int32         valid;
const PIXCMAP  *cmaps;
PIXCMAP        *cmapd;
 
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
    if (pixGetDepth(pixs) != pixGetDepth(pixd))
        return ERROR_INT("depths of pixs and pixd differ", __func__, 1);
 
    pixDestroyColormap(pixd);
    if ((cmaps = pixs->colormap) == NULL)  /* not an error */
        return 0;
    pixcmapIsValid(cmaps, NULL, &valid);
    if (!valid)
        return ERROR_INT("cmap not valid", __func__, 1);
 
    if ((cmapd = pixcmapCopy(cmaps)) == NULL)
        return ERROR_INT("cmapd not made", __func__, 1);
    pixSetColormap(pixd, cmapd);
    return 0;
}
 
 
l_ok
pixTransferAllData(PIX     *pixd,
                   PIX    **ppixs,
                   l_int32  copytext,
                   l_int32  copyformat)
{
l_int32  nbytes;
PIX     *pixs;
 
    if (!ppixs)
        return ERROR_INT("&pixs not defined", __func__, 1);
    if ((pixs = *ppixs) == NULL)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (pixs == pixd)  /* no-op */
        return ERROR_INT("pixd == pixs", __func__, 1);
 
    if (pixs->refcount == 1) {  /* transfer the data, cmap, text */
        pixFreeData(pixd);  /* dealloc any existing data */
        pixSetData(pixd, pixGetData(pixs));  /* transfer new data from pixs */
        pixs->data = NULL;  /* pixs no longer owns data */
        pixDestroyColormap(pixd);  /* free the old one, if it exists */
        pixd->colormap = pixGetColormap(pixs);  /* transfer to pixd */
        pixs->colormap = NULL;  /* pixs no longer owns colormap */
        if (copytext) {
            pixSetText(pixd, pixGetText(pixs));
            pixSetText(pixs, NULL);
        }
    } else {  /* preserve pixs by making a copy of the data, cmap, text */
        pixResizeImageData(pixd, pixs);
        nbytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
        memcpy(pixGetData(pixd), pixGetData(pixs), nbytes);
        pixCopyColormap(pixd, pixs);
        if (copytext)
            pixCopyText(pixd, pixs);
    }
 
    pixCopySpp(pixd, pixs);
    pixCopyResolution(pixd, pixs);
    pixCopyDimensions(pixd, pixs);
    if (copyformat)
        pixCopyInputFormat(pixd, pixs);
 
        /* This will destroy pixs if data was transferred;
         * otherwise, it just decrements its refcount. */
    pixDestroy(ppixs);
    return 0;
}
 
 
l_ok
pixSwapAndDestroy(PIX  **ppixd,
                  PIX  **ppixs)
{
    if (!ppixd)
        return ERROR_INT("&pixd not defined", __func__, 1);
    if (!ppixs)
        return ERROR_INT("&pixs not defined", __func__, 1);
    if (*ppixs == NULL)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (ppixs == ppixd)  /* no-op */
        return ERROR_INT("&pixd == &pixs", __func__, 1);
 
    pixDestroy(ppixd);
    *ppixd = pixClone(*ppixs);
    pixDestroy(ppixs);
    return 0;
}
 
 
/*--------------------------------------------------------------------*
 *                              Pix Accessors                         *
 *--------------------------------------------------------------------*/
l_int32
pixGetWidth(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
 
    return pix->w;
}
 
 
l_int32
pixSetWidth(PIX     *pix,
            l_int32  width)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (width < 0) {
        pix->w = 0;
        return ERROR_INT("width must be >= 0", __func__, 1);
    }
 
    pix->w = width;
    return 0;
}
 
 
l_int32
pixGetHeight(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
 
    return pix->h;
}
 
 
l_int32
pixSetHeight(PIX     *pix,
             l_int32  height)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (height < 0) {
        pix->h = 0;
        return ERROR_INT("h must be >= 0", __func__, 1);
    }
 
    pix->h = height;
    return 0;
}
 
 
l_int32
pixGetDepth(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
 
    return pix->d;
}
 
 
l_int32
pixSetDepth(PIX     *pix,
            l_int32  depth)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (depth < 1)
        return ERROR_INT("d must be >= 1", __func__, 1);
 
    pix->d = depth;
    return 0;
}
 
 
l_ok
pixGetDimensions(const PIX  *pix,
                 l_int32    *pw,
                 l_int32    *ph,
                 l_int32    *pd)
{
    if (pw) *pw = 0;
    if (ph) *ph = 0;
    if (pd) *pd = 0;
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (pw) *pw = pix->w;
    if (ph) *ph = pix->h;
    if (pd) *pd = pix->d;
    return 0;
}
 
 
l_ok
pixSetDimensions(PIX     *pix,
                 l_int32  w,
                 l_int32  h,
                 l_int32  d)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (w > 0) pixSetWidth(pix, w);
    if (h > 0) pixSetHeight(pix, h);
    if (d > 0) pixSetDepth(pix, d);
    return 0;
}
 
 
l_ok
pixCopyDimensions(PIX        *pixd,
                  const PIX  *pixs)
{
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
 
    pixSetWidth(pixd, pixGetWidth(pixs));
    pixSetHeight(pixd, pixGetHeight(pixs));
    pixSetDepth(pixd, pixGetDepth(pixs));
    pixSetWpl(pixd, pixGetWpl(pixs));
    return 0;
}
 
 
l_int32
pixGetSpp(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
 
    return pix->spp;
}
 
 
/*
 * \brief   pixSetSpp()
 *
 * \param[in]   pix
 * \param[in]   spp   1, 3 or 4 samples
 * \return  0 if OK, 1 on error
 *
 * <pre>
 * Notes:
 *      (1) For a 32 bpp pix, this can be used to ignore the
 *          alpha sample (spp == 3) or to use it (spp == 4).
 *          For example, to write a spp == 4 image without the alpha
 *          sample (as an rgb pix), call pixSetSpp(pix, 3) and
 *          then write it out as a png.
 * </pre>
 */
l_int32
pixSetSpp(PIX     *pix,
          l_int32  spp)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (spp < 1)
        return ERROR_INT("spp must be >= 1", __func__, 1);
 
    pix->spp = spp;
    return 0;
}
 
 
l_ok
pixCopySpp(PIX        *pixd,
           const PIX  *pixs)
{
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
 
    pixSetSpp(pixd, pixGetSpp(pixs));
    return 0;
}
 
 
l_int32
pixGetWpl(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
    return pix->wpl;
}
 
 
l_int32
pixSetWpl(PIX     *pix,
          l_int32  wpl)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pix->wpl = wpl;
    return 0;
}
 
 
l_int32
pixGetXRes(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
    return pix->xres;
}
 
 
l_int32
pixSetXRes(PIX     *pix,
           l_int32  res)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pix->xres = res;
    return 0;
}
 
 
l_int32
pixGetYRes(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
    return pix->yres;
}
 
 
l_int32
pixSetYRes(PIX     *pix,
           l_int32  res)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pix->yres = res;
    return 0;
}
 
 
l_ok
pixGetResolution(const PIX  *pix,
                 l_int32    *pxres,
                 l_int32    *pyres)
{
    if (pxres) *pxres = 0;
    if (pyres) *pyres = 0;
    if (!pxres && !pyres)
        return ERROR_INT("no output requested", __func__, 1);
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (pxres) *pxres = pix->xres;
    if (pyres) *pyres = pix->yres;
    return 0;
}
 
 
l_ok
pixSetResolution(PIX     *pix,
                 l_int32  xres,
                 l_int32  yres)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (xres > 0) pix->xres = xres;
    if (yres > 0) pix->yres = yres;
    return 0;
}
 
 
l_int32
pixCopyResolution(PIX        *pixd,
                  const PIX  *pixs)
{
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
 
    pixSetXRes(pixd, pixGetXRes(pixs));
    pixSetYRes(pixd, pixGetYRes(pixs));
    return 0;
}
 
 
l_int32
pixScaleResolution(PIX       *pix,
                   l_float32  xscale,
                   l_float32  yscale)
{
l_float64  xres, yres;
l_float64  maxres = 100000000.0;
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (xscale <= 0 || yscale <= 0)
        return ERROR_INT("invalid scaling ratio", __func__, 1);
 
    xres = (l_float64)xscale * (l_float32)(pix->xres) + 0.5;
    yres = (l_float64)yscale * (l_float32)(pix->yres) + 0.5;
    pix->xres = (l_uint32)L_MIN(xres, maxres);
    pix->yres = (l_uint32)L_MIN(yres, maxres);
    return 0;
}
 
 
l_int32
pixGetInputFormat(const PIX  *pix)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 0);
    return pix->informat;
}
 
 
l_int32
pixSetInputFormat(PIX     *pix,
                  l_int32  informat)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    pix->informat = informat;
    return 0;
}
 
 
l_int32
pixCopyInputFormat(PIX        *pixd,
                   const PIX  *pixs)
{
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
 
    pixSetInputFormat(pixd, pixGetInputFormat(pixs));
    return 0;
}
 
 
l_int32
pixSetSpecial(PIX     *pix,
              l_int32  special)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    pix->special = special;
    return 0;
}
 
 
char *
pixGetText(PIX  *pix)
{
    if (!pix)
        return (char *)ERROR_PTR("pix not defined", __func__, NULL);
    return pix->text;
}
 
 
l_ok
pixSetText(PIX         *pix,
           const char  *textstring)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    stringReplace(&pix->text, textstring);
    return 0;
}
 
 
l_ok
pixAddText(PIX         *pix,
           const char  *textstring)
{
char  *newstring;
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    newstring = stringJoin(pixGetText(pix), textstring);
    stringReplace(&pix->text, newstring);
    LEPT_FREE(newstring);
    return 0;
}
 
 
l_int32
pixCopyText(PIX        *pixd,
            const PIX  *pixs)
{
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    if (!pixd)
        return ERROR_INT("pixd not defined", __func__, 1);
    if (pixs == pixd)
        return 0;   /* no-op */
 
    pixSetText(pixd, pixs->text);
    return 0;
}
 
 
l_uint8 *
pixGetTextCompNew(PIX     *pix,
                  size_t  *psize)
{
char  *str;
 
    if (!pix)
        return (l_uint8 *)ERROR_PTR("pix not defined", __func__, NULL);
    str = pixGetText(pix);
    return decodeAscii85WithComp(str, strlen(str), psize);
}
 
 
l_ok
pixSetTextCompNew(PIX            *pix,
                  const l_uint8  *data,
                  size_t          size)
{
size_t  encodesize;  /* ignored */
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    LEPT_FREE(pix->text);
    pix->text = encodeAscii85WithComp(data, size, &encodesize);
    return 0;
}
 
 
PIXCMAP *
pixGetColormap(PIX  *pix)
{
    if (!pix)
        return (PIXCMAP *)ERROR_PTR("pix not defined", __func__, NULL);
    return pix->colormap;
}
 
 
l_ok
pixSetColormap(PIX      *pix,
               PIXCMAP  *colormap)
{
l_int32  valid;
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
    if (!colormap) return 0;
 
        /* Make sure the colormap doesn't get lost */
    pixDestroyColormap(pix);
    pix->colormap = colormap;
 
    pixcmapIsValid(colormap, NULL, &valid);
    if (!valid)
        return ERROR_INT("colormap is not valid", __func__, 1);
    return 0;
}
 
 
l_ok
pixDestroyColormap(PIX  *pix)
{
PIXCMAP  *cmap;
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    if ((cmap = pix->colormap) != NULL) {
        pixcmapDestroy(&cmap);
        pix->colormap = NULL;
    }
    return 0;
}
 
 
l_uint32 *
pixGetData(PIX  *pix)
{
    if (!pix)
        return (l_uint32 *)ERROR_PTR("pix not defined", __func__, NULL);
    return pix->data;
}
 
 
l_int32
pixFreeAndSetData(PIX       *pix,
                  l_uint32  *data)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pixFreeData(pix);
    pix->data = data;
    return 0;
}
 
 
l_int32
pixSetData(PIX       *pix,
           l_uint32  *data)
{
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pix->data = data;
    return 0;
}
 
 
l_int32
pixFreeData(PIX  *pix)
{
l_uint32  *data;
 
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    if ((data = pixGetData(pix)) != NULL) {
        pixdata_free(data);
        pix->data = NULL;
    }
    return 0;
}
 
 
l_uint32 *
pixExtractData(PIX  *pixs)
{
l_int32    bytes;
l_uint32  *data, *datas;
 
    if (!pixs)
        return (l_uint32 *)ERROR_PTR("pixs not defined", __func__, NULL);
 
    if (pixs->refcount == 1) {  /* extract */
        data = pixGetData(pixs);
        pixSetData(pixs, NULL);
    } else {  /* refcount > 1; copy */
        bytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
        datas = pixGetData(pixs);
        if ((data = (l_uint32 *)pixdata_malloc(bytes)) == NULL)
            return (l_uint32 *)ERROR_PTR("data not made", __func__, NULL);
        memcpy(data, datas, bytes);
    }
 
    return data;
}
 
 
/*--------------------------------------------------------------------*
 *                          Pix line ptrs                             *
 *--------------------------------------------------------------------*/
void **
pixGetLinePtrs(PIX      *pix,
               l_int32  *psize)
{
l_int32    i, h, wpl;
l_uint32  *data;
void     **lines;
 
    if (psize) *psize = 0;
    if (!pix)
        return (void **)ERROR_PTR("pix not defined", __func__, NULL);
 
    h = pixGetHeight(pix);
    if (psize) *psize = h;
    if ((lines = (void **)LEPT_CALLOC(h, sizeof(void *))) == NULL)
        return (void **)ERROR_PTR("lines not made", __func__, NULL);
    wpl = pixGetWpl(pix);
    data = pixGetData(pix);
    for (i = 0; i < h; i++)
        lines[i] = (void *)(data + i * wpl);
 
    return lines;
}
 
 
/*--------------------------------------------------------------------*
 *                         Pix Size Comparisons                       *
 *--------------------------------------------------------------------*/
l_int32
pixSizesEqual(const PIX  *pix1,
              const PIX  *pix2)
{
    if (!pix1 || !pix2)
        return ERROR_INT("pix1 and pix2 not both defined", __func__, 0);
 
    if (pix1 == pix2)
        return 1;
 
    if ((pixGetWidth(pix1) != pixGetWidth(pix2)) ||
        (pixGetHeight(pix1) != pixGetHeight(pix2)) ||
        (pixGetDepth(pix1) != pixGetDepth(pix2)))
        return 0;
    else
        return 1;
}
 
 
l_ok
pixMaxAspectRatio(PIX        *pixs,
                  l_float32  *pratio)
{
l_int32  w, h;
 
    if (!pratio)
        return ERROR_INT("&ratio not defined", __func__, 1);
    *pratio = -1.0;
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
    pixGetDimensions(pixs, &w, &h, NULL);
    if (w == 0 || h == 0) {
        L_ERROR("invalid size: w = %d, h = %d\n", __func__, w, h);
        return 1;
    }
 
    *pratio = L_MAX((l_float32)h / (l_float32)w, (l_float32)w / (l_float32)h);
    return 0;
}
 
 
/*--------------------------------------------------------------------*
 *                    Print output for debugging                      *
 *--------------------------------------------------------------------*/
extern const char *ImageFileFormatExtensions[];
 
l_ok
pixPrintStreamInfo(FILE        *fp,
                   const PIX   *pix,
                   const char  *text)
{
l_int32         informat;
const PIXCMAP  *cmap;
 
    if (!fp)
        return ERROR_INT("fp not defined", __func__, 1);
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    if (text)
        fprintf(fp, "  Pix Info for %s:\n", text);
    fprintf(fp, "    width = %d, height = %d, depth = %d, spp = %d\n",
            pixGetWidth(pix), pixGetHeight(pix), pixGetDepth(pix),
            pixGetSpp(pix));
    fprintf(fp, "    wpl = %d, data = %p, refcount = %d\n",
            pixGetWpl(pix), pix->data, pix->refcount);
    fprintf(fp, "    xres = %d, yres = %d\n", pixGetXRes(pix), pixGetYRes(pix));
    if ((cmap = pix->colormap) != NULL)
        pixcmapWriteStream(fp, cmap);
    else
        fprintf(fp, "    no colormap\n");
    informat = pixGetInputFormat(pix);
    fprintf(fp, "    input format: %d (%s)\n", informat,
            ImageFileFormatExtensions[informat]);
    if (pix->text != NULL)
        fprintf(fp, "    text: %s\n", pix->text);
 
    return 0;
}