gi-gdk4-4.0.10: Gdk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gdk.Objects.Texture

Contents

- Exported types
- Methods
  - download
  - getColorState
  - getFormat
  - getHeight
  - getWidth
  - newForPixbuf
  - newFromBytes
  - newFromFile
  - newFromFilename
  - newFromResource
  - saveToPng
  - saveToPngBytes
  - saveToTiff
  - saveToTiffBytes
- Properties
  - colorState
  - height
  - width

Description

Refers to pixel data in various forms.

It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time.

There are various ways to create `GdkTexture` objects from a `Pixbuf`, or from bytes stored in memory, a file, or a `Resource`.

The ownership of the pixel data is transferred to the `GdkTexture` instance; you can only make a copy of it, via `textureDownload`.

`GdkTexture` is an immutable object: That means you cannot change anything about it other than increasing the reference count via `objectRef`, and consequently, it is a threadsafe object.

GDK provides a number of threadsafe texture loading functions: `textureNewFromResource`, `textureNewFromBytes`, `textureNewFromFile`, `textureNewFromFilename`, `textureNewForPixbuf`. Note that these are meant for loading icons and resources that are shipped with the toolkit or application. It is recommended that you use a dedicated image loading framework such as glycin, if you need to load untrusted image data.

Synopsis

- newtype Texture = Texture (ManagedPtr Texture)
- class (GObject o, IsDescendantOf Texture o) => IsTexture o
- toTexture :: (MonadIO m, IsTexture o) => o -> m Texture
- textureDownload :: (HasCallStack, MonadIO m, IsTexture a) => a -> Ptr Word8 -> CSize -> m ()
- textureGetColorState :: (HasCallStack, MonadIO m, IsTexture a) => a -> m ColorState
- textureGetFormat :: (HasCallStack, MonadIO m, IsTexture a) => a -> m MemoryFormat
- textureGetHeight :: (HasCallStack, MonadIO m, IsTexture a) => a -> m Int32
- textureGetWidth :: (HasCallStack, MonadIO m, IsTexture a) => a -> m Int32
- textureNewForPixbuf :: (HasCallStack, MonadIO m, IsPixbuf a) => a -> m Texture
- textureNewFromBytes :: (HasCallStack, MonadIO m) => Bytes -> m Texture
- textureNewFromFile :: (HasCallStack, MonadIO m, IsFile a) => a -> m Texture
- textureNewFromFilename :: (HasCallStack, MonadIO m) => [Char] -> m Texture
- textureNewFromResource :: (HasCallStack, MonadIO m) => Text -> m Texture
- textureSaveToPng :: (HasCallStack, MonadIO m, IsTexture a) => a -> [Char] -> m Bool
- textureSaveToPngBytes :: (HasCallStack, MonadIO m, IsTexture a) => a -> m Bytes
- textureSaveToTiff :: (HasCallStack, MonadIO m, IsTexture a) => a -> [Char] -> m Bool
- textureSaveToTiffBytes :: (HasCallStack, MonadIO m, IsTexture a) => a -> m Bytes
- constructTextureColorState :: (IsTexture o, MonadIO m) => ColorState -> m (GValueConstruct o)
- getTextureColorState :: (MonadIO m, IsTexture o) => o -> m ColorState
- constructTextureHeight :: (IsTexture o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getTextureHeight :: (MonadIO m, IsTexture o) => o -> m Int32
- constructTextureWidth :: (IsTexture o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getTextureWidth :: (MonadIO m, IsTexture o) => o -> m Int32

# Exported types

newtype Texture Source #

Memory-managed wrapper type.

Constructors

Texture (ManagedPtr Texture) |

#### Instances

Instances details

Eq Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture Methods (==) :: Texture -> Texture -> Bool Source # (/=) :: Texture -> Texture -> Bool Source #
GObject Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture
ManagedPtrNewtype Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture Methods toManagedPtr :: Texture -> ManagedPtr Texture Source #
TypedObject Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture Methods glibType :: IO GType Source #
HasParentTypes Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture
IsGValue (Maybe Texture) Source # | Convert `Texture` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gdk.Objects.Texture Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Texture -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Texture) Source #
type ParentTypes Texture Source # |
Instance details Defined in GI.Gdk.Objects.Texture type ParentTypes Texture = '[Object, Paintable, Icon, LoadableIcon]

class (GObject o, IsDescendantOf Texture o) => IsTexture o Source #

Type class for types which can be safely cast to `Texture`, for instance with `toTexture`.

#### Instances

Instances details

(GObject o, IsDescendantOf Texture o) => IsTexture o Source # |
Instance details Defined in GI.Gdk.Objects.Texture

toTexture :: (MonadIO m, IsTexture o) => o -> m Texture Source #

Cast to `Texture`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, computeConcreteSize, download, equal, forceFloating, freezeNotify, getv, hash, invalidateContents, invalidateSize, isFloating, load, loadAsync, loadFinish, notify, notifyByPspec, ref, refSink, runDispose, saveToPng, saveToPngBytes, saveToTiff, saveToTiffBytes, serialize, snapshot, stealData, stealQdata, thawNotify, toString, unref, watchClosure.

#### Getters

getColorState, getCurrentImage, getData, getFlags, getFormat, getHeight, getIntrinsicAspectRatio, getIntrinsicHeight, getIntrinsicWidth, getProperty, getQdata, getWidth.

#### Setters

setData, setDataFull, setProperty.

## download

textureDownload Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> Ptr Word8 | `data`: pointer to enough memory to be filled with the downloaded data of `texture`
-> CSize | `stride`: rowstride in bytes
-> m () |

Downloads the `texture` into local memory.

This may be an expensive operation, as the actual texture data may reside on a GPU or on a remote display server.

The data format of the downloaded data is equivalent to `FormatArgb32`, so every downloaded pixel requires 4 bytes of memory.

Downloading a texture into a Cairo image surface:

### c code

    surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
                                          gdk_texture_get_width (texture),
                                          gdk_texture_get_height (texture));
    gdk_texture_download (texture,
                          cairo_image_surface_get_data (surface),
                          cairo_image_surface_get_stride (surface));
    cairo_surface_mark_dirty (surface);

For more flexible download capabilities, see `TextureDownloader`.

## getColorState

textureGetColorState Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `self`: a `GdkTexture`
-> m ColorState | Returns: the color state of the `GdkTexture`

Returns the color state associated with the texture.

Since: 4.16

## getFormat

textureGetFormat Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `self`: a GdkTexture
-> m MemoryFormat | Returns: the preferred format for the texture's data

Gets the memory format most closely associated with the data of the texture.

Note that it may not be an exact match for texture data stored on the GPU or with compression.

The format can give an indication about the bit depth and opacity of the texture and is useful to determine the best format for downloading the texture.

Since: 4.10

## getHeight

textureGetHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> m Int32 | Returns: the height of the `GdkTexture`

Returns the height of the `texture`, in pixels.

## getWidth

textureGetWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> m Int32 | Returns: the width of the `GdkTexture`

Returns the width of `texture`, in pixels.

## newForPixbuf

textureNewForPixbuf Source #

Arguments

:: (HasCallStack, MonadIO m, IsPixbuf a) |
=> a | `pixbuf`: a `GdkPixbuf`
-> m Texture | Returns: a new `GdkTexture`

Deprecated: (Since version 4.20)Use e.g. libglycin, which can load many imageformats into a `GdkTexture`

Creates a new texture object representing the `GdkPixbuf`.

This function is threadsafe, so that you can e.g. use GTask and `taskRunInThread` to avoid blocking the main thread while loading a big image.

## newFromBytes

textureNewFromBytes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `GBytes` containing the data to load
-> m Texture | Returns: A newly-created `GdkTexture` (Can throw `GError`)

Creates a new texture by loading an image from memory,

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If `NULL` is returned, then `error` will be set.

This function is threadsafe, so that you can e.g. use GTask and `taskRunInThread` to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`.

Since: 4.6

## newFromFile

textureNewFromFile Source #

Arguments

:: (HasCallStack, MonadIO m, IsFile a) |
=> a | `file`: `GFile` to load
-> m Texture | Returns: A newly-created `GdkTexture` (Can throw `GError`)

Creates a new texture by loading an image from a file.

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If `NULL` is returned, then `error` will be set.

This function is threadsafe, so that you can e.g. use GTask and `taskRunInThread` to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`.

## newFromFilename

textureNewFromFilename Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `path`: the filename to load
-> m Texture | Returns: A newly-created `GdkTexture` (Can throw `GError`)

Creates a new texture by loading an image from a file.

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If `NULL` is returned, then `error` will be set.

This function is threadsafe, so that you can e.g. use GTask and `taskRunInThread` to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`.

Since: 4.6

## newFromResource

textureNewFromResource Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `resourcePath`: the path of the resource file
-> m Texture | Returns: A newly-created `GdkTexture`

Creates a new texture by loading an image from a resource.

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

It is a fatal error if `resourcePath` does not specify a valid image resource and the program will abort if that happens. If you are unsure about the validity of a resource, use `textureNewFromFile` to load it.

This function is threadsafe, so that you can e.g. use GTask and `taskRunInThread` to avoid blocking the main thread while loading a big image.

## saveToPng

textureSaveToPng Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> [Char] | `filename`: the filename to store to
-> m Bool | Returns: `True` if saving succeeded, `False` on failure.

Store the given `texture` to the `filename` as a PNG file.

This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a `File` or other location, you might want to use `textureSaveToPngBytes` or look into the libglycin library.

## saveToPngBytes

textureSaveToPngBytes Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> m Bytes | Returns: a newly allocated `GBytes` containing PNG data

Store the given `texture` in memory as a PNG file.

Use `textureNewFromBytes` to read it back.

If you want to serialize a texture, this is a convenient and portable way to do that.

If you need more control over the generated image, such as attaching metadata, you should look into an image handling library such as the libglycin library.

If you are dealing with high dynamic range float data, you might also want to consider `textureSaveToTiffBytes` instead.

Since: 4.6

## saveToTiff

textureSaveToTiff Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> [Char] | `filename`: the filename to store to
-> m Bool | Returns: `True` if saving succeeded, `False` on failure.

Store the given `texture` to the `filename` as a TIFF file.

GTK will attempt to store data without loss.

Since: 4.6

## saveToTiffBytes

textureSaveToTiffBytes Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a) |
=> a | `texture`: a `GdkTexture`
-> m Bytes | Returns: a newly allocated `GBytes` containing TIFF data

Store the given `texture` in memory as a TIFF file.

Use `textureNewFromBytes` to read it back.

This function is intended to store a representation of the texture's data that is as accurate as possible. This is particularly relevant when working with high dynamic range images and floating-point texture data.

If that is not your concern and you are interested in a smaller size and a more portable format, you might want to use `textureSaveToPngBytes`.

Since: 4.6

# Properties

## colorState

The color state of the texture.

Since: 4.16

constructTextureColorState :: (IsTexture o, MonadIO m) => ColorState -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`color-state`” property. This is rarely needed directly, but it is used by `new`.

getTextureColorState :: (MonadIO m, IsTexture o) => o -> m ColorState Source #

Get the value of the “`color-state`” property. When overloading is enabled, this is equivalent to

    get texture #colorState

## height

The height of the texture, in pixels.

constructTextureHeight :: (IsTexture o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`height`” property. This is rarely needed directly, but it is used by `new`.

getTextureHeight :: (MonadIO m, IsTexture o) => o -> m Int32 Source #

Get the value of the “`height`” property. When overloading is enabled, this is equivalent to

    get texture #height

## width

The width of the texture, in pixels.

constructTextureWidth :: (IsTexture o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`width`” property. This is rarely needed directly, but it is used by `new`.

getTextureWidth :: (MonadIO m, IsTexture o) => o -> m Int32 Source #

Get the value of the “`width`” property. When overloading is enabled, this is equivalent to

    get texture #width