Top |
Functions
VipsRegion * | vips_region_new () |
int | vips_region_buffer () |
int | vips_region_image () |
int | vips_region_region () |
int | vips_region_equalsregion () |
int | vips_region_position () |
void | vips_region_paint () |
void | vips_region_paint_pel () |
void | vips_region_black () |
void | vips_region_copy () |
int | vips_region_shrink_method () |
int | vips_region_shrink () |
int | vips_region_prepare () |
int | vips_region_prepare_to () |
VipsPel * | vips_region_fetch () |
int | vips_region_width () |
int | vips_region_height () |
void | vips_region_invalidate () |
#define | VIPS_COUNT_PIXELS() |
#define | VIPS_REGION_LSKIP() |
#define | VIPS_REGION_N_ELEMENTS() |
#define | VIPS_REGION_SIZEOF_ELEMENT() |
#define | VIPS_REGION_SIZEOF_PEL() |
#define | VIPS_REGION_SIZEOF_LINE() |
#define | VIPS_REGION_ADDR() |
#define | VIPS_REGION_ADDR_TOPLEFT() |
Description
A VipsRegion is a small part of an image. You use regions to read pixels out of images without having to have the whole image in memory at once.
A region can be a memory buffer, part of a memory-mapped file, part of some other image, or part of some other region.
Regions must be created, used and freed all within the same thread, since
they can reference private per-thread caches. VIPS sanity-checks region
ownership in various places, so you are likely to see g_assert()
errors if
you don't follow this rule.
There is API to transfer ownership of regions between threads, but hopefully this is only needed within VIPS, so we don't expose it. Hopefully.
Functions
vips_region_new ()
VipsRegion *
vips_region_new (VipsImage *image
);
Create a region. VipsRegion s start out empty, you need to call
vips_region_prepare()
to fill them with pixels.
See also: vips_region_prepare()
.
[constructor]
vips_region_buffer ()
int vips_region_buffer (VipsRegion *reg
,const VipsRect *r
);
The region is transformed so that at least r
pixels are available as a
memory buffer that can be written to.
[method]
vips_region_image ()
int vips_region_image (VipsRegion *reg
,const VipsRect *r
);
The region is transformed so that at least r
pixels are available to be
read from the image. The image needs to be a memory buffer or represent a
file on disc that has been mapped or can be mapped.
[method]
vips_region_region ()
int vips_region_region (VipsRegion *reg
,VipsRegion *dest
,const VipsRect *r
,int x
,int y
);
Make VIPS_REGION_ADDR()
on reg
go to dest
instead.
r
is the part of reg
which you want to be able to address (this
effectively becomes the valid field), (x
, y
) is the top LH corner of the
corresponding area in dest
.
Performs all clipping necessary to ensure that reg->valid
is indeed
valid.
If the region we attach to is moved or destroyed, we can be left with dangling pointers! If the region we attach to is on another image, the two images must have the same sizeof( pel ).
[method]
Parameters
reg |
region to operate upon |
|
dest |
region to connect to |
|
r |
VipsRect of pixels you need to be able to address |
|
x |
postion of |
|
y |
postion of |
vips_region_equalsregion ()
int vips_region_equalsregion (VipsRegion *reg1
,VipsRegion *reg2
);
Do two regions point to the same piece of image? ie.
1 2 3 |
VIPS_REGION_ADDR( reg1, x, y ) == VIPS_REGION_ADDR( reg2, x, y ) && *VIPS_REGION_ADDR( reg1, x, y ) == *VIPS_REGION_ADDR( reg2, x, y ) for all x, y, reg1, reg2. |
vips_region_position ()
int vips_region_position (VipsRegion *reg
,int x
,int y
);
Set the position of a region. This only affects reg->valid, ie. the way pixels are addressed, not reg->data, the pixels which are addressed. Clip against the size of the image. Do not allow negative positions, or positions outside the image.
[method]
vips_region_paint ()
void vips_region_paint (VipsRegion *reg
,const VipsRect *r
,int value
);
Paints value
into reg
covering rectangle r
.
r
is clipped against
reg->valid
.
For int images, value
is
passed to memset()
, so it usually needs to be 0 or 255. For float images,
value is cast to a float and copied in to each band element.
r
is clipped against
reg->valid
.
See also: vips_region_black()
.
[method]
vips_region_paint_pel ()
void vips_region_paint_pel (VipsRegion *reg
,const VipsRect *r
,const VipsPel *ink
);
Paints ink
into reg
covering rectangle r
. r
is clipped against
reg->valid
.
ink
should be a byte array of the same size as an image pixel containing
the binary value to write into the pixels.
See also: vips_region_paint()
.
[method]
vips_region_black ()
void
vips_region_black (VipsRegion *reg
);
Paints 0 into the valid part of reg
.
See also: vips_region_paint()
.
[method]
vips_region_copy ()
void vips_region_copy (VipsRegion *reg
,VipsRegion *dest
,const VipsRect *r
,int x
,int y
);
Copy from one region to another. Copy area r
from inside reg
to dest
,
positioning the area of pixels at x
, y
. The two regions must have pixels
which are the same size.
See also: vips_region_paint()
.
Parameters
reg |
source region |
|
dest |
destination region. |
[inout] |
r |
VipsRect of pixels you need to copy |
|
x |
postion of |
|
y |
postion of |
vips_region_shrink_method ()
int vips_region_shrink_method (VipsRegion *from
,VipsRegion *to
,const VipsRect *target
,VipsRegionShrink method
);
Write the pixels target
in to
from the x2 larger area in from
.
Non-complex uncoded images and LABQ only. Images with alpha (see
vips_image_hasalpha()
) shrink with pixels scaled by alpha to avoid fringing.
method
selects the method used to do the 2x2 shrink.
See also: vips_region_copy()
.
Parameters
from |
source region |
|
to |
destination region. |
[inout] |
target |
VipsRect of pixels you need to copy |
|
method |
method to use when generating target pixels |
vips_region_shrink ()
int vips_region_shrink (VipsRegion *from
,VipsRegion *to
,const VipsRect *target
);
Write the pixels target
in to
from the x2 larger area in from
.
Non-complex uncoded images and LABQ only. Images with alpha (see
vips_image_hasalpha()
) shrink with pixels scaled by alpha to avoid fringing.
This is a compatibility stub that just calls vips_region_shrink_method()
.
See also: vips_region_shrink_method()
.
[skip]
Parameters
from |
source region |
|
to |
destination region. |
[inout] |
target |
VipsRect of pixels you need to copy |
vips_region_prepare ()
int vips_region_prepare (VipsRegion *reg
,const VipsRect *r
);
vips_region_prepare() fills reg
with pixels. After calling,
you can address at least the area r
with VIPS_REGION_ADDR()
and get
valid pixels.
vips_region_prepare() runs in-line, that is, computation is done by the calling thread, no new threads are involved, and computation blocks until the pixels are ready.
Use vips_sink_screen()
to calculate an area of pixels in the
background.
See also: vips_sink_screen()
,
vips_region_prepare_to()
.
[method]
vips_region_prepare_to ()
int vips_region_prepare_to (VipsRegion *reg
,VipsRegion *dest
,const VipsRect *r
,int x
,int y
);
Like vips_region_prepare()
: fill reg
with the pixels in area r
.
Unlike vips_region_prepare()
, rather than writing the result to reg
, the
pixels are written into dest
at offset x
, y
.
Also unlike vips_region_prepare()
, dest
is not set up for writing for
you with vips_region_buffer()
. You can
point dest
at anything, and pixels really will be written there.
This makes vips_region_prepare_to()
useful for making the ends of
pipelines.
See also: vips_region_prepare()
, vips_sink_disc()
.
[method]
Parameters
reg |
region to prepare |
|
dest |
region to write to. |
[inout] |
r |
VipsRect of pixels you need to be able to address |
|
x |
postion of |
|
y |
postion of |
vips_region_fetch ()
VipsPel * vips_region_fetch (VipsRegion *region
,int left
,int top
,int width
,int height
,size_t *len
);
Generate an area of pixels and return a copy. The result must be freed
with g_free()
. The requested area must be completely inside the image.
This is equivalent to vips_region_prepare()
, followed by a memcpy. It is
convenient for language bindings.
[method]
vips_region_invalidate ()
void
vips_region_invalidate (VipsRegion *reg
);
Mark a region as containing invalid pixels. Calling this function means
that the next time vips_region_prepare()
is called, the region will be
recalculated.
This is faster than calling vips_image_invalidate_all()
, but obviously only
affects a single region.
See also: vips_image_invalidate_all()
, vips_region_prepare()
.
[method]
VIPS_REGION_ADDR()
#define VIPS_REGION_ADDR( R, X, Y )
This macro returns a pointer to a pixel in a region. The (X
, Y
)
coordinates need to be within the VipsRect (R->valid
).
If DEBUG is defined, you get a version that checks bounds for you.
See also: vips_region_prepare()
.
VIPS_REGION_ADDR_TOPLEFT()
#define VIPS_REGION_ADDR_TOPLEFT( R ) ((R)->data)
This macro returns a pointer to the top-left pixel in the VipsRegion, that
is, the pixel at (R->valid.left
, R->valid.top
).
See also: vips_region_prepare()
.