man/lqr_carver_bias_set_energy_function.3

   1 .\"     Title: \fBlqr_carver_set_energy_function\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_SET_ENERGY_FUNCT" "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_bias_set_energy_function \- set a custom energy function for a LqrCarver object
  15 .SH "SYNOPSIS"
  16 .sp
  17 .ft B
  18 .nf
  19 #include <lqr\&.h>
  20 .fi
  21 .ft
  22 .HP 41
  23 .BI "LqrRetVal lqr_carver_set_energy_function(LqrCarver*\ " "carver" ", LqrEnergyFunc\ " "en_func" ", gint\ " "radius" ", LqrEnergyReaderType\ " "reader_type" ", gpointer\ " "extra_data" ");"
  24 .SH "DESCRIPTION"
  25 .PP
  26 The function
  27 \fBlqr_carver_set_energy_function\fR
  28 assigns the energy function
  29 \fIen_func\fR
  30 to the
  31 LqrCarver
  32 object pointed to by
  33 \fIcarver\fR
  34 (see below for more details on custom functions definitions)\&.
  35 .PP
  36 The parameter
  37 \fIradius\fR
  38 determines the size of the square region which affects the computation around each pixel (the side of the square will be
  39 2 * \fIradius\fR + 1
  40 pixels long)\&.
  41 .PP
  42 The parameter
  43 \fIreader_type\fR
  44 sets the reader type used when reading the image, and therefore it determines what quantity will be passed on to the function
  45 \fIen_func\fR
  46 (see below for more details on reader types)\&.
  47 .PP
  48 The parameter
  49 \fIextra_data\fR
  50 is a (void) pointer which can be used to pass on additional values to the function
  51 \fIef_func\fR\&.
  52 .SH "CUSTOM FUNCTIONS DEFINITION"
  53 .PP
  54 The function
  55 \fIen_func\fR
  56 must be of type
  57 LqrEnergyFunc, whose prototype is defined by:
  58 .sp
  59 .RS 4
  60 .nf
  61 typedef gfloat (*LqrEnergyFunc) (gint x, gint y, gint img_width, gint img_height, LqrReadingWindow * rwindow, gpointer extra_data);
  62
  63 .fi
  64 .RE
  65 .sp
  66 Such a function is expected to compute the energy at pixel
  67 \fIx\fR,
  68 \fIy\fR
  69 based on the knowledge of the current image size (obtained from
  70 \fIwidth\fR
  71 and
  72 \fIheight\fR) and the content of the image in a square around that pixel, which is passed through the
  73 \fIrwindow\fR
  74 reading window\&.
  75 .PP
  76 In most cases, the parameters
  77 \fIx\fR,
  78 \fIy\fR,
  79 \fIwidth\fR
  80 and
  81 \fIheight\fR
  82 would only be used to determine whether the region under consideration is at the image boundary or not\&.
  83 .PP
  84 The
  85 \fIrwindow\fR
  86 content must be read using the function
  87 \fBlqr_rwindow_read\fR(3)\&.
  88 .SH "READER TYPES"
  89 .PP
  90 The
  91 \fBLqrEnergyReaderType\fR
  92 is an enum which can take these values (also noted is the number of channels of the corresponging reading window):
  93 .PP
  94 LQR_ER_BRIGHT
  95 .RS 4
  96 brightness (1 channel)
  97 .RE
  98 .PP
  99 LQR_ER_BRIGHT
 100 .RS 4
 101 luma (1 channel)
 102 .RE
 103 .PP
 104 LQR_ER_RGBA
 105 .RS 4
 106 RGBA (4 channels)
 107 .RE
 108 .PP
 109 LQR_ER_CUSTOM
 110 .RS 4
 111 read the normalised image channels as they are (as many channels as the image has)
 112 .RE
 113 These readouts always return values beetween
 114 0
 115 and
 116 1\&.
 117 .PP
 118 Note that these readouts may have special meanings depending on the image type:
 119 .sp
 120 .RS 4
 121 \h'-04'\(bu\h'+03'for
 122 LQR_GREY_IMAGE,
 123 LQR_GREYA_IMAGE
 124 and
 125 LQR_CUSTOM_IMAGE
 126 images, the
 127 LQR_ER_LUMA
 128 readout will yield the same result as
 129 LQR_ER_BRIGHT
 130 .RE
 131 .sp
 132 .RS 4
 133 \h'-04'\(bu\h'+03'for
 134 LQR_CUSTOM_IMAGE
 135 images, the
 136 LQR_ER_BRIGHT
 137 readout will return the average pixel value (additive, i\&.e\&. if a black channel is present the channel values will be inverted and multiplied by the black channel inverse), multiplied by the alpha channel value\&.
 138 .RE
 139 .sp
 140 .RS 4
 141 \h'-04'\(bu\h'+03'for
 142 LQR_CUSTOM_IMAGE
 143 images, the
 144 LQR_ER_RGBA
 145 readout
 146 \fIcannot be used\fR: it will always return
 147 0
 148 .RE
 149 .sp
 150 .RE
 151 .SH "RETURN VALUE"
 152 .PP
 153 The return value follows the Liquid Rescale library signalling system\&.
 154 .SH "SEE ALSO"
 155 .PP
 156
 157 \fBlqr_carver_set_energy_function_builtin\fR(3), \fBlqr_carver_get_energy\fR(3), \fBlqr_rwindow_read\fR(3), \fBlqr_rwindow_get_read_t\fR(3), \fBlqr_rwindow_get_radius\fR(3), \fBlqr_rwindow_get_channels\fR(3)
 158 .SH "COPYRIGHT"
 159 Copyright \(co 2007-2009 Carlo Baldassi
 160 .br