man/lqr_carver_scan.3

   1 .\"     Title: \fBlqr_carver_scan\fR
   2 .\"    Author: Carlo Baldassi
   3 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   4 .\"      Date: 4 Maj 2009
   5 .\"    Manual: LqR library API reference
   6 .\"    Source: LqR library 0.4.0 API (3:0:3)
   7 .\"
   8 .TH "\FBLQR_CARVER_SCAN\FR" "3" "4 Maj 2009" "LqR library 0.4.0 API (3:0:3)" "LqR library API reference"
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 lqr_carver_scan, lqr_carver_scan_ext \- read out a multi-size image one pixel at a time
  15 .SH "SYNOPSIS"
  16 .sp
  17 .ft B
  18 .nf
  19 #include <lqr\&.h>
  20 .fi
  21 .ft
  22 .HP 25
  23 .BI "gboolean lqr_carver_scan(LqrCarver*\ " "carver" ", gint*\ " "x" ", gint*\ " "y" ", guchar**\ " "rgb" ");"
  24 .HP 29
  25 .BI "gboolean lqr_carver_scan_ext(LqrCarver*\ " "carver" ", gint*\ " "x" ", gint*\ " "y" ", void**\ " "rgb" ");"
  26 .SH "DESCRIPTION"
  27 .PP
  28 The functions
  29 \fBlqr_carver_scan\fR
  30 and
  31 \fBlqr_carver_scan_ext\fR
  32 are used to read out the multi\-size image contained in the
  33 LqrCarver
  34 object pointed to by
  35 \fIcarver\fR
  36 one pixel at a time\&. They store the pixel coordinates in the variables pointed to by
  37 \fIx\fR
  38 and
  39 \fIy\fR, and the pixel content in the array pointed to by
  40 \fIrgb\fR; then they move the readout pointer to the next pixel, or they reset it if the end of the image is reached\&.
  41 .PP
  42 The first one must only be used on the
  43 LqrCarver
  44 objects created with
  45 \fIlqr_carver_new\fR, i\&.e\&. with 8\-bit images, while the second one is general (see
  46 \fBLqrColDepth\fR(3)), but the
  47 \fIrgb\fR
  48 pointer must be cast to the appropriate type to be used (i\&.e pass the address of a pointer to
  49 void
  50 to the function
  51 \fBlqr_carver_scan_ext\fR, then cast it to a pointer of the appropriate type and use this last one for reading the output)\&.
  52 .PP
  53 The
  54 \fIrgb\fR
  55 variable will point to an array which is internal to the
  56 LqrCarver
  57 object, so there is no need to allocate memory for it\&. However, it should only be accessed right after a call to the scan functions, and writing to it must be avoided\&.
  58 .SH "RETURN VALUE"
  59 .PP
  60 These functions return
  61 TRUE
  62 in case the readout is successful and the end of the image was not reached,
  63 FALSE
  64 otherwise\&. If
  65 \fBlqr_carver_scan\fR
  66 is called over a non\-8\-bit
  67 LqrCarver
  68 object, it will return
  69 FALSE\&.
  70 .SH "SEE ALSO"
  71 .PP
  72
  73 \fBLqrColDepth\fR(3), \fBlqr_carver_scan_reset\fR(3), \fBlqr_carver_scan_line\fR(3)
  74 .SH "COPYRIGHT"
  75 Copyright \(co 2007-2009 Carlo Baldassi
  76 .br