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
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
Memory-managed wrapper type.
Constructors
Texture (ManagedPtr Texture) |
Instances
Eq Texture Source # | |
GObject Texture Source # | |
Defined in GI.Gdk.Objects.Texture | |
ManagedPtrNewtype Texture Source # | |
Defined in GI.Gdk.Objects.Texture Methods toManagedPtr :: Texture -> ManagedPtr Texture # | |
TypedObject Texture Source # | |
Defined in GI.Gdk.Objects.Texture | |
HasParentTypes Texture Source # | |
Defined in GI.Gdk.Objects.Texture | |
IsGValue (Maybe Texture) Source # | Convert |
Defined in GI.Gdk.Objects.Texture Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe Texture -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe Texture) # | |
type ParentTypes Texture Source # | |
Defined in GI.Gdk.Objects.Texture |
Methods
Click to display all available methods, including inherited ones
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
download
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> Ptr Word8 |
|
-> CSize |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> m ColorState | Returns: the color state of the |
Returns the color state associated with the texture.
Since: 4.16
getFormat
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> m Int32 | Returns: the height of the |
Returns the height of the texture
, in pixels.
getWidth
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> m Int32 | Returns: the width of the |
Returns the width of texture
, in pixels.
newForPixbuf
Arguments
:: (HasCallStack, MonadIO m, IsPixbuf a) | |
=> a |
|
-> m Texture | Returns: a new |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m Texture | Returns: A newly-created |
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
Arguments
:: (HasCallStack, MonadIO m, IsFile a) | |
=> a |
|
-> m Texture | Returns: A newly-created |
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] |
|
-> m Texture | Returns: A newly-created |
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 |
|
-> m Texture | Returns: A newly-created |
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
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> [Char] |
|
-> m Bool |
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 |
|
-> m Bytes | Returns: a newly allocated |
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
Arguments
:: (HasCallStack, MonadIO m, IsTexture a) | |
=> a |
|
-> [Char] |
|
-> m Bool |
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 |
|
-> m Bytes | Returns: a newly allocated |
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