Optionalproperties: Partial<Cogl.Texture.ConstructorProps>Internal$signalsCompile-time signal type information.
This instance property is generated only for TypeScript type checking. It is not defined at runtime and should not be accessed in JS code.
Static$gtypeConstruct OnlycontextConstruct OnlyformatConstruct OnlyheightConstruct OnlyloaderConstruct OnlywidthExplicitly allocates the storage for the given texture which
allows you to be sure that there is enough memory for the
texture and if not then the error can be handled gracefully.
Normally applications don't need to use this api directly since the texture will be implicitly allocated when data is set on the texture, or if the texture is attached to a Cogl.Offscreen framebuffer and rendered too.
true if the texture was successfully allocated, otherwise false and error will be updated if it wasn't null.
SignalconnectSignalconnect_SignalemitAllows you to manually iterate the low-level textures that define a given region of a high-level Cogl.Texture.
For example cogl_texture_2d_sliced_new_with_size() can be used to
create a meta texture that may slice a large image into multiple,
smaller power-of-two sized textures. These high level textures are
not directly understood by a GPU and so this API must be used to
manually resolve the underlying textures for drawing.
All high level textures (Cogl.AtlasTexture, Cogl.SubTexture and Cogl.Texture2DSliced) can be handled consistently using this interface which greately simplifies implementing primitives that support all texture types.
For example if you use the cogl_rectangle() API then Cogl will
internally use this API to resolve the low level textures of any
meta textures you have associated with CoglPipeline layers.
The low level drawing APIs such as cogl_primitive_draw()
don't understand the Cogl.Texture interface and so it is your
responsibility to use this API to resolve all CoglPipeline textures
into low-level textures before drawing.
For each low-level texture that makes up part of the given region
of the meta_texture, callback is called specifying how the
low-level texture maps to the original region.
The top-left x coordinate of the region to iterate
The top-left y coordinate of the region to iterate
The bottom-right x coordinate of the region to iterate
The bottom-right y coordinate of the region to iterate
The wrap mode for the x-axis
The wrap mode for the y-axis
A Cogl.TextureForeachCallback pointer to be called for each low-level texture within the specified region.
Queries what components the given texture stores internally as set
via cogl_texture_set_components().
For textures created by the ‘_with_size’ constructors the default is Cogl.TextureComponents.RGBA. The other constructors which take a %CoglBitmap or a data pointer default to the same components as the pixel format of the data.
Copies the pixel data from a cogl texture to system memory.
Don't pass the value of cogl_texture_get_rowstride() as the
rowstride argument, the rowstride should be the rowstride you
want for the destination data buffer not the rowstride of the
source texture
the Cogl.PixelFormat to store the texture as.
the rowstride of data in bytes or pass 0 to calculate from the bytes-per-pixel of format multiplied by the texture width.
memory location to write the texture's contents, or null to only query the data size through the return value.
the size of the texture data in bytes
Queries the GL handles for a GPU side texture through its Cogl.Texture.
If the texture is spliced the data for the first sub texture will be queried.
true if the handle was successfully retrieved, false if the handle was invalid
Queries the height of a cogl texture.
the height of the GPU side texture in pixels
Queries the pre-multiplied alpha status for internally stored red,
green and blue components for the given texture as set by
cogl_texture_set_premultiplied().
By default the pre-multiplied state is TRUE.
true if red, green and blue components are internally stored pre-multiplied by the alpha value or false if not.
Queries the width of a cogl texture.
the width of the GPU side texture in pixels
Queries if a texture is sliced (stored as multiple GPU side tecture objects).
true if the texture is sliced, false if the texture is stored as a single GPU texture
Affects the internal storage format for this texture by specifying what components will be required for sampling later.
This api affects how data is uploaded to the GPU since unused components can potentially be discarded from source data.
For textures created by the ‘_with_size’ constructors the default is Cogl.TextureComponents.RGBA. The other constructors which take a %CoglBitmap or a data pointer default to the same components as the pixel format of the data.
Note that the Cogl.TextureComponents.RG format is not available on all drivers. The availability can be determined by checking for the Cogl.FeatureID.OGL_FEATURE_ID_TEXTURE_RG feature. If this format is used on a driver where it is not available then Cogl.TextureError.FORMAT will be raised when the texture is allocated. Even if the feature is not available then Cogl.PixelFormat.RG_88 can still be used as an image format as long as Cogl.TextureComponents.RG isn't used as the texture's components.
texture a Cogl.Texture.
Sets all the pixels for a given mipmap level by copying the pixel
data pointed to by the data argument into the given texture.
data should point to the first pixel to copy corresponding
to the top left of the mipmap level being set.
If rowstride equals 0 then it will be automatically calculated
from the width of the mipmap level and the bytes-per-pixel for the
given format.
A mipmap level of 0 corresponds to the largest, base image of a
texture and level 1 is half the width and height of level 0. If
dividing any dimension of the previous level by two results in a
fraction then round the number down (floor()), but clamp to 1
something like this:
next_width = MAX (1, floor (prev_width));
You can determine the number of mipmap levels for a given texture like this:
n_levels = 1 + floor (log2 (max_dimension));
Where %max_dimension is the larger of cogl_texture_get_width() and
cogl_texture_get_height().
It is an error to pass a level number >= the number of levels that
texture can have according to the above calculation.
Since the storage for a Cogl.Texture is allocated lazily then
if the given texture has not previously been allocated then this
api can return false and throw an exceptional error if there is
not enough memory to allocate storage for texture.
the Cogl.PixelFormat used in the source data buffer.
rowstride of the source data buffer (computed from the texture width and format if it equals 0)
the source data, pointing to the first top-left pixel to set
The mipmap level to update (Normally 0 for the largest, base texture)
true if the data upload was successful, and false otherwise
Affects the internal storage format for this texture by specifying whether red, green and blue color components should be stored as pre-multiplied alpha values.
This api affects how data is uploaded to the GPU since Cogl will convert source data to have premultiplied or unpremultiplied components according to this state.
For example if you create a texture via
cogl_texture_2d_new_with_size() and then upload data via
cogl_texture_set_data() passing a source format of
Cogl.PixelFormat.RGBA_8888 then Cogl will internally multiply the
red, green and blue components of the source data by the alpha
component, for each pixel so that the internally stored data has
pre-multiplied alpha components. If you instead upload data that
already has pre-multiplied components by passing
Cogl.PixelFormat.RGBA_8888_PRE as the source format to
cogl_texture_set_data() then the data can be uploaded without being
converted.
By default the premultipled state is TRUE.
Whether any internally stored red, green or blue components are pre-multiplied by an alpha component.
Sets the pixels in a rectangular subregion of texture from an in-memory
buffer containing pixel data.
The region set can't be larger than the source data
upper left coordinate to use from source data.
upper left coordinate to use from source data.
upper left destination horizontal coordinate.
upper left destination vertical coordinate.
width of destination region to write. (Must be less than or equal to width)
height of destination region to write. (Must be less than or equal to height)
width of source data buffer.
height of source data buffer.
the Cogl.PixelFormat used in the source buffer.
rowstride of source buffer (computed from width if none specified)
the actual pixel data.
true if the subregion upload was successful, and false otherwise
Copies a specified source region from bitmap to the position
(src_x, src_y) of the given destination texture handle.
The region updated can't be larger than the source bitmap
upper left coordinate to use from the source bitmap.
upper left coordinate to use from the source bitmap
upper left destination horizontal coordinate.
upper left destination vertical coordinate.
width of destination region to write. (Must be less than or equal to the bitmap width)
height of destination region to write. (Must be less than or equal to the bitmap height)
The source bitmap to read from
true if the subregion upload was successful, and false otherwise
Staticerror_Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget GObject.Object instance to be updated with the same value of the "active" property of the action GObject.Object instance.
If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
GObject.Binding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A GObject.Object can have multiple bindings.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of
g_object_bind_property_full(), using GClosures instead of
function pointers.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
a GObject.Closure wrapping the transformation function from the source to the target, or null to use the default
a GObject.Closure wrapping the transformation function from the target to the source, or null to use the default
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Blocks a handler of an instance so it will not be called during any signal emissions
Handler ID of the handler to be blocked
Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to.
Handler ID of the handler to be disconnected
This function is intended for GObject.Object implementations to re-enforce
a [floating][floating-ref] object reference. Doing this is seldom
required: all GInitiallyUnowneds are created with a floating reference
which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
GObject.Object::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling GObject.Value.unset.
Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.
The name of the property to get
Return location for the property value. Can be an empty GObject.Value initialized by G_VALUE_INIT (auto-initialized with expected type since GLib 2.60), a GObject.Value initialized with the expected property type, or a GObject.Value initialized with a transformable type
This function gets back user data pointers stored via
g_object_set_qdata().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Checks whether object has a [floating][floating-ref] reference.
true if object has a floating reference
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than
g_object_notify().
One way to avoid using g_object_notify() from within the
class that registered the properties, and using g_object_notify_by_pspec()
instead, is to store the GParamSpec used with
g_object_class_install_property() inside a static array, e.g.:
typedef enum
{
PROP_FOO = 1,
PROP_LAST
} MyObjectProperty;
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
0, 100,
50,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the GObject.ParamSpec of a property installed on the class of object.
Increases the reference count of object.
Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type
of object will be propagated to the return type (using the GCC typeof()
extension), so any casting the caller needs to do on the return type must be
explicit.
the same object
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
object
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.
Object containing the properties to set
Sets a property on an object.
The name of the property to set
The value to set the property to
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
the data if found, or null if no such data exists.
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of
g_object_steal_qdata() would have left the destroy function set,
and thus the partial string list would have been freed upon
g_object_set_qdata_full().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Stops a signal's emission by the given signal name. This will prevent the default handler and any subsequent signal handlers from being invoked.
Name of the signal to stop emission of
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one GObject.Object::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Unblocks a handler so it will be called again during any signal emissions
Handler ID of the handler to be unblocked
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the GObject.Object may be reused in future (for example, if it is
an instance variable of another object), it is recommended to clear the
pointer to null rather than retain a dangling pointer to a potentially
invalid GObject.Object instance. Use g_clear_object() for this.
Virtualvfunc_the constructed function is called by g_object_new() as the
final step of the object creation process. At the point of the call, all
construction properties have been set on the object. The purpose of this
call is to allow for object initialisation steps that can only be performed
after construction properties have been set. constructed implementors
should chain up to the constructed call of their parent class to allow it
to complete its initialisation.
Virtualvfunc_Virtualvfunc_the dispose function is supposed to drop all references to other
objects, but keep the instance otherwise intact, so that client method
invocations still work. It may be run multiple times (due to reference
loops). Before returning, dispose should chain up to the dispose method
of the parent class.
Virtualvfunc_instance finalization function, should finish the finalization of
the instance begun in dispose and chain up to the finalize method of the
parent class.
Virtualvfunc_Virtualvfunc_Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
Virtualvfunc_the generic setter for all properties of this type. Should be
overridden for every type with properties. If implementations of
set_property don't emit property change notification explicitly, this will
be done implicitly by the type system. However, if the notify signal is
emitted explicitly, the type system will not emit it a second time.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
GObject.Closure to watch
Static_Staticcompat_Staticfind_Staticinstall_Staticinstall_the id for the new property
the GObject.ParamSpec for the new property
Staticinterface_Find the GObject.ParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Staticinterface_Add a property to an interface; this is only useful for interfaces
that are added to GObject-derived types. Adding a property to an
interface forces all objects classes with that interface to have a
compatible property. The compatible property could be a newly
created GObject.ParamSpec, but normally
g_object_class_override_property() will be used so that the object
class only needs to provide an implementation and inherits the
property description, default value, bounds, and so forth from the
interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
GObject.TypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the GObject.ParamSpec for the new property
Staticinterface_Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Staticlist_StaticnewvStaticoverride_the new property ID
the name of a property registered in a parent class or in an interface of this class.
Functions for creating and manipulating textures
Cogl allows creating and manipulating textures using a uniform API that tries to hide all the various complexities of creating, loading and manipulating textures.