Gegl.Buffer

g GObject.Object GObject.Object Gegl.TileSource Gegl.TileSource GObject.Object->Gegl.TileSource Gegl.Buffer Gegl.Buffer Gegl.TileHandler Gegl.TileHandler Gegl.TileHandler->Gegl.Buffer Gegl.TileSource->Gegl.TileHandler

Subclasses:

None

Methods

Inherited:

Gegl.TileHandler (5), GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

load (path)

class

new (format_name, x, y, width, height)

class

new_for_backend (extent, backend)

class

open (path)

class

swap_create_file (suffix)

class

swap_has_file (path)

class

swap_remove_file (path)

add_handler (handler)

clear (roi)

copy (src_rect, repeat_mode, dst, dst_rect)

create_sub_buffer (extent)

dup ()

flush ()

flush_ext (rect)

freeze_changed ()

get (rect, scale, format_name, repeat_mode)

get_abyss ()

get_extent ()

linear_close (linear)

remove_handler (handler)

sample_cleanup ()

save (path, roi)

set (rect, format_name, src)

set_abyss (abyss)

set_color (rect, color)

set_color_from_pixel (rect, pixel, pixel_format)

set_extent (extent)

set_pattern (rect, pattern, x_offset, y_offset)

share_storage (buffer2)

signal_connect (detailed_signal, c_handler, *data)

thaw_changed ()

Virtual Methods

Inherited:

GObject.Object (7)

Properties

Inherited:

Gegl.TileHandler (1)

Name

Type

Flags

Short Description

abyss-height

int

r/w/co

pixel height of abyss

abyss-width

int

r/w/co

pixel width of abyss

abyss-x

int

r/w/co

abyss-y

int

r/w/co

backend

Gegl.TileBackend

r/w/co

A custom tile-backend instance to use

format

int

r/w/c

babl format

height

int

r/w/c

pixel height of buffer

initialized

bool

r/w/co

path

str

r/w/co

URI to where the buffer is stored

pixels

int

r

total amount of pixels in image (width x height)

px-size

int

r

size of a single pixel in bytes.

shift-x

int

r/w/co

shift-y

int

r/w/co

tile-height

int

r/w/co

height of a tile

tile-width

int

r/w/co

width of a tile

width

int

r/w/c

pixel width of buffer

x

int

r/w/c

local origin’s offset relative to source origin

y

int

r/w/c

local origin’s offset relative to source origin

Signals

Inherited:

GObject.Object (1)

Name

Short Description

changed

Fields

Inherited:

GObject.Object (1)

Class Details

class Gegl.Buffer(**kwargs)
Bases:

Gegl.TileHandler

Abstract:

No

classmethod load(path)
Parameters:

path (str) – the path to a gegl buffer on disk.

Returns:

a Gegl.Buffer object.

Return type:

Gegl.Buffer

Loads an existing Gegl.Buffer from disk, if it has previously been saved with Gegl.Buffer.save it should be possible to open through any GIO transport, buffers that have been used as swap needs random access to be opened.

classmethod new(format_name, x, y, width, height)
Parameters:
  • format_name (str) – The Babl.Object format name for this buffer, e.g. “RGBA float”

  • x (int) – x origin of the buffer’s extent

  • y (int) – y origin of the buffer’s extent

  • width (int) – width of the buffer’s extent

  • height (int) – height of the buffer’s extent

Return type:

Gegl.Buffer

Create a new Gegl.Buffer with the given format and dimensions.

classmethod new_for_backend(extent, backend)
Parameters:
Return type:

Gegl.Buffer

Create a new Gegl.Buffer from a backend, if None is passed in the extent of the buffer will be inherited from the extent of the backend.

returns a Gegl.Buffer, that holds a reference to the provided backend.

classmethod open(path)
Parameters:

path (str) – the path to a gegl buffer on disk.

Returns:

a Gegl.Buffer object.

Return type:

Gegl.Buffer

Open an existing on-disk Gegl.Buffer, this buffer is opened in a monitored state so multiple instances of gegl can share the same buffer. Sets on one buffer are reflected in the other.

classmethod swap_create_file(suffix)
Parameters:

suffix (str or None) – a string to suffix the filename with, for identification purposes, or None.

Returns:

a string containing the full file path, or None is the swap is disabled. The returned string should be freed with GLib.free() when no longer needed.

Return type:

str or None

Generates a unique filename in the GEGL swap directory, suitable for using as swap space. When the file is no longer needed, it may be removed with Gegl.Buffer.swap_remove_file(); otherwise, it will be removed when Gegl.exit() is called.

classmethod swap_has_file(path)
Parameters:

path (str) – a filename

Return type:

bool

Tests if path is a swap file, that is, if it has been created with Gegl.Buffer.swap_create_file(), and hasn’t been removed yet.

classmethod swap_remove_file(path)
Parameters:

path (str) – the swap file to remove, as returned by Gegl.Buffer.swap_create_file()

Removes a swap file, generated using Gegl.Buffer.swap_create_file(), unlinking the file, if exists.

add_handler(handler)
Parameters:

handler (object or None) – a Gegl.TileHandler

Add a new tile handler in the existing chain of tile handler of a Gegl.Buffer.

clear(roi)
Parameters:

roi (Gegl.Rectangle) – a rectangular region

Clears the provided rectangular region by setting all the associated memory to 0.

copy(src_rect, repeat_mode, dst, dst_rect)
Parameters:
  • src_rect (Gegl.Rectangle) – source rectangle (or None to copy entire source buffer)

  • repeat_mode (Gegl.AbyssPolicy) – the abyss policy to be using if src_rect is outside src’s extent.

  • dst (Gegl.Buffer) – destination buffer.

  • dst_rect (Gegl.Rectangle) – position of upper left destination pixel (or None to match src_rect)

Copy a region from source buffer to destination buffer.

If the babl_formats of the buffers are the same, and the tile boundaries align, this will create copy-on-write tiles in the destination buffer.

This function never does any scaling. When src_rect and dst_rect do not have the same width and height, the size of src_rect is used.

create_sub_buffer(extent)
Parameters:

extent (Gegl.Rectangle) – coordinates of new buffer.

Returns:

the new sub buffer

Return type:

Gegl.Buffer

Create a new sub Gegl.Buffer, that is a view on a larger buffer.

dup()
Returns:

the new buffer

Return type:

Gegl.Buffer

Duplicate a buffer (internally uses Gegl.Buffer.copy). Aligned tiles will create copy-on-write clones in the new buffer.

flush()

Flushes all unsaved data to disk, this is not necessary for shared geglbuffers opened with Gegl.Buffer.open since they auto-sync on writes.

flush_ext(rect)
Parameters:

rect (Gegl.Rectangle) – rectangle

Invokes the external flush function, if any is set on the provided buffer - this ensures that data pending - in the current implementation only OpenCL - externally to be synchronized with the buffer. Multi threaded code should call such a synchronization before branching out to avoid each of the threads having an implicit synchronization of its own.

freeze_changed()

Blocks emission of the “changed” signal for self.

While the signal is blocked, changes to self are accumulated, and will be emitted once the signal is unblocked, using Gegl.Buffer.thaw_changed().

get(rect, scale, format_name, repeat_mode)
Parameters:
  • rect (Gegl.Rectangle) – the coordinates we want to retrieve data from.

  • scale (float) – sampling scale, 1.0 = pixel for pixel 2.0 = magnify, 0.5 scale down.

  • format_name (str or None) – the format to store data in, if None the format of the buffer is used.

  • repeat_mode (Gegl.AbyssPolicy) – how requests outside the buffer extent are handled. Valid values: GEGL_ABYSS_NONE (abyss pixels are zeroed), GEGL_ABYSS_WHITE (abyss pixels are white), GEGL_ABYSS_BLACK (abyss pixels are black), GEGL_ABYSS_CLAMP (coordinates are clamped to the abyss rectangle), GEGL_ABYSS_LOOP (buffer contents are tiled if outside of the abyss rectangle).

Returns:

A copy of the requested data

Return type:

bytes

Fetch a rectangular linear buffer of pixel data from the Gegl.Buffer.

get_abyss()
Return type:

Gegl.Rectangle

Return the abyss extent of a buffer, this expands out to the parents extent in subbuffers.

get_extent()
Return type:

Gegl.Rectangle

Returns a pointer to a Gegl.Rectangle structure defining the geometry of a specific Gegl.Buffer, this is also the default width/height of buffers passed in to Gegl.Buffer.set and Gegl.Buffer.get (with a scale of 1.0 at least).

linear_close(linear)
Parameters:

linear (object or None) – a previously returned buffer.

This function makes sure Gegl.Buffer and underlying code is aware of changes being made to the linear buffer. If the request was not a compatible one it is written back to the buffer. Multiple concurrent users can be handed the same buffer (both raw access and converted).

remove_handler(handler)
Parameters:

handler (object or None) – a Gegl.TileHandler

Remove the provided tile handler in the existing chain of tile handler of a Gegl.Buffer.

sample_cleanup()

Clean up resources used by sampling framework of buffer.

Deprecated since version 0.4.2: This function has no effect. It is not necessary to call it after using gegl_buffer_sample() or gegl_buffer_sample_at_level().

save(path, roi)
Parameters:
  • path (str) – the path where the gegl buffer will be saved, any writable GIO uri is valid.

  • roi (Gegl.Rectangle) – the region of interest to write, this is the tiles that will be collected and written to disk.

Write a Gegl.Buffer to a file.

set(rect, format_name, src)
Parameters:
  • rect (Gegl.Rectangle) – the rectangle to write.

  • format_name (str) – the format of the input data.

  • src (bytes) – pixel data to write to self.

Store a linear raster buffer into the Gegl.Buffer.

set_abyss(abyss)
Parameters:

abyss (Gegl.Rectangle) – new abyss.

Return type:

bool

Changes the size and position of the abyss rectangle of a buffer.

Returns True if the change of abyss was successful.

set_color(rect, color)
Parameters:

Sets the region covered by rect to the specified color.

set_color_from_pixel(rect, pixel, pixel_format)
Parameters:
  • rect (Gegl.Rectangle) – a rectangular region to fill with a color.

  • pixel (object or None) – pointer to the data of a single pixel

  • pixel_format (Babl.Object) – the babl format of the pixel, if missing - the soft format of dst.

Sets the region covered by rect to the the provided pixel.

set_extent(extent)
Parameters:

extent (Gegl.Rectangle) – new extent.

Return type:

bool

Changes the size and position that is considered active in a buffer, this operation is valid on any buffer, reads on subbuffers outside the master buffer’s extent are at the moment undefined.

Returns True if the change of extent was successful.

set_pattern(rect, pattern, x_offset, y_offset)
Parameters:
  • rect (Gegl.Rectangle) – the region of self to fill

  • pattern (Gegl.Buffer) – a Gegl.Buffer to be repeated as a pattern

  • x_offset (int) – where the pattern starts horizontally

  • y_offset (int) – where the pattern starts vertical

Fill a region with a repeating pattern. Offsets parameters are relative to the origin (0, 0) and not to the rectangle. So be carefull about the origin of pattern and self extents.

share_storage(buffer2)
Parameters:

buffer2 (Gegl.Buffer) – a Gegl.Buffer.

Return type:

bool

Checks if a pair of buffers share the same underlying tile storage.

Returns True if self and buffer2 share the same storage.

signal_connect(detailed_signal, c_handler, *data)
Parameters:
  • detailed_signal (str) – only “changed” expected for now

  • c_handler (GObject.Callback) – c function callback

  • data (object or None) – user data:

Returns:

an handle like g_signal_connect.

Return type:

int

This function should be used instead of g_signal_connect when connecting to the Gegl.Buffer ::changed signal handler, Gegl.Buffer contains additional machinery to avoid the overhead of changes when no signal handler have been connected, if regular g_signal_connect is used; then no signals will be emitted.

thaw_changed()

Unblocks emission of the “changed” signal for self.

Once all calls to Gegl.Buffer.freeze_changed() are matched by corresponding calls to Gegl.Buffer.freeze_changed(), all accumulated changes are emitted.

Signal Details

Gegl.Buffer.signals.changed(buffer, object)
Signal Name:

changed

Flags:

RUN_LAST, NO_RECURSE, NO_HOOKS

Parameters:

Property Details

Gegl.Buffer.props.abyss_height
Name:

abyss-height

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

pixel height of abyss

Gegl.Buffer.props.abyss_width
Name:

abyss-width

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

pixel width of abyss

Gegl.Buffer.props.abyss_x
Name:

abyss-x

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Gegl.Buffer.props.abyss_y
Name:

abyss-y

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Gegl.Buffer.props.backend
Name:

backend

Type:

Gegl.TileBackend

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

A custom tile-backend instance to use

Gegl.Buffer.props.format
Name:

format

Type:

int

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

babl format

Gegl.Buffer.props.height
Name:

height

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE, CONSTRUCT

pixel height of buffer

Gegl.Buffer.props.initialized
Name:

initialized

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Gegl.Buffer.props.path
Name:

path

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

URI to where the buffer is stored

Gegl.Buffer.props.pixels
Name:

pixels

Type:

int

Default Value:

0

Flags:

READABLE

total amount of pixels in image (width x height)

Gegl.Buffer.props.px_size
Name:

px-size

Type:

int

Default Value:

0

Flags:

READABLE

size of a single pixel in bytes.

Gegl.Buffer.props.shift_x
Name:

shift-x

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Gegl.Buffer.props.shift_y
Name:

shift-y

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Gegl.Buffer.props.tile_height
Name:

tile-height

Type:

int

Default Value:

128

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

height of a tile

Gegl.Buffer.props.tile_width
Name:

tile-width

Type:

int

Default Value:

128

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

width of a tile

Gegl.Buffer.props.width
Name:

width

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE, CONSTRUCT

pixel width of buffer

Gegl.Buffer.props.x
Name:

x

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT

local origin’s offset relative to source origin

Gegl.Buffer.props.y
Name:

y

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT

local origin’s offset relative to source origin