Classes |
Public Member Functions |
Static Public Member Functions |
Protected Member Functions |
Static Protected Member Functions |
Friends |
List of all members
kanzi::Texture Class Reference
Textures provide images that can be used with image nodes, texture brushes and materials for use in 3D rendering or material brushes. More...
#include <kanzi/core.ui/platform/graphics_backend/gl/texture.hpp>
Inheritance diagram for kanzi::Texture:
Classes | |
| struct | CreateInfo |
| Struct which contains all the parameters that are needed for texture creation. More... | |
| struct | CreateInfo2D |
| Texture creation parameters for two dimensional texture. More... | |
| struct | CreateInfoCubemap |
| Texture creation parameters for cubemap texture that is initialized from six images. More... | |
| struct | CreateInfoCubemapRenderTarget |
| Use Texture::CreateInfoCubemapRenderTarget to create a Cubemap Render Target Texture resource. More... | |
| struct | CreateInfoHostCopy2D |
| Texture creation parameters for two dimensional texture that is updated from the CPU. More... | |
| struct | CreateInfoNode2DRenderTarget |
| Texture creation parameters for texture that can be used as render target for 2D nodes. More... | |
| struct | CreateInfoRenderpassRenderTarget |
| Texture creation parameters for texture that can be used as render target for renderpasses. More... | |
Public Member Functions | |
| void | generateMipmaps () |
| Generates the mipmaps from the base level image. | |
| GraphicsFormat | getDepthStencilFormat () const |
| Returns depth/stencil format of the texture. | |
| RenderbufferSharedPtr | getDepthStencilRenderbuffer () const |
| Returns internal depth/stencil renderbuffer. | |
| unsigned int | getHeightDivisor () const |
| Gets height divisor for automatic sizes. | |
| BitmapImageSharedPtr | getHostCopyImage () const |
| Returns the host-side memory copy of a non-cubemap texture, if available. | |
| BitmapImageSharedPtr | getHostCopyImage (Face face, unsigned int slice) const |
| Returns the host-side memory copy of texture data as an image, if available. | |
| NativeDeploymentTarget | getNativeDeploymentTarget () const |
| Returns the native deployment target. | |
| NativeFramebufferHandle | getNativeFramebufferHandle () const |
| Gets native framebuffer handle for the texture. | |
| NativeTextureHandle | getNativeHandle () const |
| Gets native texture handle for the texture. | |
| RenderTargetMode | getRenderTargetMode () const |
| Returns rendertarget mode of the texture. | |
| const Sampler & | getSampler () const |
| Returns the Sampler used by the texture. | |
| TextureType | getType () const |
| Returns type of the texture. | |
| unsigned int | getWidthDivisor () const |
| Gets width divisor for automatic sizes. | |
| bool | hasAutomaticHeight () const |
| Indicates whether height is or should be automatically calculated. | |
| bool | hasAutomaticWidth () const |
| Indicates whether width is or should be automatically calculated. | |
| void | reattachFramebuffer () |
| Reattaches the internal framebuffer object. | |
| void | reattachFramebuffer (RenderbufferSharedPtr colorRenderbuffer) |
| Reattaches the internal framebuffer object and includes the renderbuffer given as parameter. | |
| void | reattachFramebuffer (TextureSharedPtr depthTexture) |
| Reattaches the internal framebuffer object and includes the depth texture given as parameter. | |
| void | recreate (CreateInfo &createInfo) |
| Validates the CreateInfo texture descriptor, creates a new texture and swaps it in place. | |
| void | resize (unsigned width, unsigned height) |
| Changes the size of the texture. | |
| void | resolveMSAA (Renderer &renderer) |
| Resolves the internal multisample anti-aliasing renderbuffer to a single sample texture, if necessary. | |
| void | setData (const kanzi::byte *data) |
| Sets the texture data for base level of a non-cubemap texture. | |
| void | setData (Face face, unsigned int mipmapLevel, unsigned int x, unsigned int y, unsigned int width, unsigned int height, const kanzi::byte *data) |
| Sets the texture data for the specified area in a texture. | |
| void | setData (unsigned int mipmapLevel, unsigned int x, unsigned int y, unsigned int width, unsigned int height, const kanzi::byte *data) |
| Sets the texture data for the specified area in the texture. | |
| void | setHeightDivisor (unsigned int divisor) |
| Sets the height divisor. | |
| void | setWidthDivisor (unsigned int divisor) |
| Sets the wight divisor. | |
 Public Member Functions inherited from kanzi::Surface | |
| void | attach (Usage usage, APIAttachment apiAttachment, Face face, unsigned int mipmapLevel) |
| Attach surface to framebuffer. | |
| unsigned int | getFaceCount () const |
| Get number of faces. This should be six for cubemaps and one for everything else. | |
| unsigned int | getFeatures () const |
| Get features for Surface. | |
| GraphicsFormat | getFormat () const |
| Get GraphicsFormat of Surface. | |
| unsigned int | getHeight () const |
| Get height in pixels. | |
| unsigned int | getMipmapLevelCount () const |
| Get number of mipmap levels. | |
| unsigned int | getRenderTargetSampleCount () const |
| Get number of multisample samples for Surface. | |
| unsigned int | getSliceCount () const |
| Get number of slices. | |
| unsigned int | getWidth () const |
| Get width in pixels. | |
| Public Member Functions inherited from kanzi::GPUResource | |
| void | destroy () |
| Destroys a GPU resource. | |
| unsigned int | getGPUMemoryUsage () const |
| Renderer * | getRenderer () const |
| void | invalidate () |
| Notify resource that graphics context was lost and all GPU resources are invalid. | |
| bool | isDeployed () const |
| ~GPUResource () override | |
| Public Member Functions inherited from kanzi::Resource | |
| virtual unsigned int | getCPUMemoryUsage () const |
| Function for getting the memory usage of a resource. | |
| const string & | getName () const |
| Gets the resource name. | |
| const string & | getUrl () const |
| Gets the resource URL. | |
| bool | isKeepAlive () const |
| Tells if the resource has keep alive flag set. | |
| void | reload () |
| void | reloadFromFile (string_view filePath) |
| void | reloadFromKzb (KzbFile &kzbFile, ReadOnlyMemoryFile &file, KzbMemoryParser &parser) |
| void | setKeepAlive (bool keepAlive) |
| Sets the keep alive flag. | |
| void | setUrl (string_view url) |
| Sets the resource URL. | |
| ~Resource () override | |
| Destructor. | |
| Public Member Functions inherited from kanzi::Object | |
| AppliedStyleEntrySharedPtr | applyObjectStyle (kanzi::StyleSharedPtr style) |
| Applies a style to an object. | |
| void | applyObjectStyles () |
| Apply all styles for an object node. | |
| Domain * | getDomain () const |
| Returns the domain the object belongs to. | |
| const Metaclass * | getDynamicMetaclass () const override |
| Returns the metaclass of the dynamic type of the object. | |
| MainLoopScheduler * | getMainLoopScheduler () const |
| Returns the MainLoopScheduler instance of the associated Domain. | |
| detail::MessageDispatcher * | getMessageDispatcher () const |
| Returns the message dispatcher of the object. | |
| ResourceManager * | getResourceManager () const |
| Returns the resource manager of the object. | |
| ScriptingContextSharedPtr | getScriptingContext () const |
| Gets the scripting context of the object. | |
| Object (Domain *domain) | |
| void | setScriptingContext (ScriptingContextSharedPtr context) |
| Sets the scripting context of the object. | |
| void | unapplyObjectStyle (AppliedStyleEntrySharedPtr appliedStyleEntry) |
| void | unapplyObjectStyles () |
| Unapplies and removes all applied styles. | |
| ~Object () override | |
| Public Member Functions inherited from kanzi::MetaObject | |
| bool | isTypeOf (const Metaclass *objectType) const |
| Determines if the type of this object is the given type or derived from it. | |
| virtual | ~MetaObject () |
| Public Member Functions inherited from kanzi::PropertyObject | |
| template<typename DataType > | |
| void | addPropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner) |
| template<typename DataType > | |
| void | addPropertyModifierWithoutNotifyingHandlers (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner) |
| Adds a property modifier without notifying handlers. | |
| template<typename DataType > | |
| void | addPropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner) |
| template<typename DataType > | |
| void | addPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, PropertyValuePrecedence precedence, AbstractPropertyTypeDescriptor::ValueSourceOwner *owner) |
| template<typename DataType > | |
| void | addPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, PropertyValuePrecedence precedence, void *ownerPointer) |
| PropertyStorageContainer::iterator | beginPropertyStorage () |
| Returns the begin iterator to the internal property storage container. | |
| PropertyStorageContainer::const_iterator | beginPropertyStorage () const |
| Returns the begin iterator to the internal property storage container. | |
| void | clearPropertyFlag (AbstractPropertyType propertyType, uint32_t flag) |
| void | copyLocalValue (const PropertyObject &other, AbstractPropertyType propertyType) |
| Copies local value of single property from another object. | |
| void | copyLocalValues (const PropertyObject &other) |
| Copies all local values from another object. | |
| PropertyStorageContainer::iterator | endPropertyStorage () |
| Returns the end iterator to the internal property storage container. | |
| PropertyStorageContainer::const_iterator | endPropertyStorage () const |
| Returns the end iterator to the internal property storage container. | |
| template<typename DataType > | |
| PropertyType< DataType >::Traits::ReturnType | getAbstractProperty (AbstractPropertyType abstractPropertyType) const |
| template<typename DataType > | |
| PropertyType< DataType >::Traits::ReturnType | getAbstractPropertyBase (AbstractPropertyType abstractPropertyType) const |
| template<typename DataType > | |
| optional< typename PropertyType< DataType >::Traits::ReturnType > | getOptionalAbstractProperty (AbstractPropertyType abstractPropertyType) const |
| template<typename DataType > | |
| optional< typename PropertyType< DataType >::Traits::ReturnType > | getOptionalProperty (const PropertyType< DataType > &propertyType) const |
| Evaluates the property value in the same way as the overload above but does not default to the value in property metadata if there are no inputs to the property value. | |
| template<typename DataType > | |
| optional< typename PropertyType< DataType >::Traits::ReturnType > | getOptionalPropertyBase (const PropertyType< DataType > &propertyType) const |
| Returns the current value of a property disregarding modifiers, but does not default to the value in property metadata if there are no inputs to the property value. | |
| template<typename DataType > | |
| PropertyType< DataType >::Traits::ReturnType | getProperty (const PropertyType< DataType > &propertyType) const |
| Returns the current value of a property type. | |
| template<typename DataType > | |
| PropertyType< DataType >::Traits::ReturnType | getPropertyBase (const PropertyType< DataType > &propertyType) const |
| Returns the current value of a property disregarding modifiers. | |
| template<typename DataType > | |
| size_t | getPropertyNotificationHandlerCount (const PropertyType< DataType > &propertyType) const |
| Gets number of current notification handlers for given property type. | |
| bool | hasBaseValue (AbstractPropertyType propertyType) const |
| Evaluates whether there are any inputs into the property value, disregarding modifiers. | |
| bool | hasLocalValue (AbstractPropertyType propertyType) const |
| Evaluates whether there is a local value set for the property. | |
| bool | hasNonClassValue (AbstractPropertyType propertyType) const |
| Evaluates whether there is a value of any precedence higher than class default value set for the property. | |
| bool | hasValue (AbstractPropertyType propertyType) const |
| Evaluates whether there are any inputs into the property value. | |
| bool | isPropertyFlagSet (AbstractPropertyType propertyType, uint32_t flag) const |
| virtual void | onPropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) |
| Virtual function to handle property change notifications. | |
| PropertyObject () | |
| void | removeKzbProperties () |
| Remove all KZB properties. | |
| void | removeKzbProperties (flat_set< AbstractPropertyType > *keepProperties) |
| Remove all KZB properties that are not included in a given set. | |
| template<typename DataType > | |
| void | removeLocalPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, void *ownerPointer) |
| void | removeLocalValue (AbstractPropertyType propertyType) |
| Removes the local value associated with the property. | |
| template<typename DataType > | |
| void | removePropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner) |
| template<typename DataType > | |
| void | removePropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner) |
| template<typename DataType > | |
| void | removePropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, void *ownerPointer) |
| template<typename DataType > | |
| void | setAbstractProperty (AbstractPropertyType abstractPropertyType, typename PropertyType< DataType >::Traits::ParameterType value) |
| template<typename DataType > | |
| void | setProperty (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Traits::ParameterType value) |
| Sets the local value of a property type. | |
| void | setPropertyFlag (AbstractPropertyType propertyType, uint32_t flag) |
| KZ_DEPRECATED void | validatePropertyModifiers (AbstractPropertyType propertyType) |
| Validates property modifiers and notifies handlers. | |
| void | validatePropertyModifiersAndNotifyHandlers (AbstractPropertyType propertyType) |
| Validates property modifiers and notifies handlers. | |
| virtual | ~PropertyObject () |
Static Public Member Functions | |
| static TextureSharedPtr | create (Domain *domain, const CreateInfo &createInfo, string_view name) |
| Creates a texture with specified texture creation parameters. | |
| static TextureSharedPtr | create (Domain *domain, TextureType type, int nativeHandle, bool takeOwnership, GraphicsFormat format, unsigned int mipmapLevelCount, unsigned int width, unsigned int height, string_view name) |
| Creates texture from a pre-existing GL texture object. | |
| static ResourceManager::LoadTaskSharedPtr | createGenericFileLoadTask (string_view name, unique_ptr< File > file, Domain *domain) |
| Create a task used to create a Texture from generic file. | |
| static ResourceManager::LoadTaskSharedPtr | createLoadTask (string_view name, KzbFile *kzbFile, ReadOnlyMemoryFilePtr file) |
| Create a task used to create a Texture from KZB File. | |
| Static Public Member Functions inherited from kanzi::Object | |
| static const Metaclass * | getStaticMetaclass () |
| Returns the metaclass of Object class. | |
| static PropertyTypeEditorInfoSharedPtr | makeEditorInfo () |
| Default implementation that returns empty editor info. | |
| Static Public Member Functions inherited from kanzi::MetaObject | |
| static const Metaclass * | getStaticMetaclass () |
| Returns the metaclass of Object class. | |
| static PropertyTypeEditorInfoSharedPtr | makeEditorInfo () |
| Default implementation that returns empty editor info. | |
Static Protected Member Functions | |
| static GLFramebufferHandle | makeFramebuffer (Renderer *renderer, const CreateInfo &createInfo) |
| Helper function to create GL framebuffer object. | |
| static vector< BitmapImageSharedPtr > | makeHostCopyImages (const CreateInfo &createInfo) |
| Helper function to allocate host images. | |
| static GLTextureHandle | makeTexture (Renderer *renderer, const CreateInfo &createInfo) |
| Helper function to create GL texture object. | |
Friends | |
| class | ResourceManager |
| void | swap (Texture &texture1, Texture &texture2) |
Detailed Description
Textures provide images that can be used with image nodes, texture brushes and materials for use in 3D rendering or material brushes.
Textures can be set as render target. Texture can be set to as render target for either 2d node or render pass, but not both.
For details on the render target texture, see RenderTargetMode, CreateInfoNode2DRenderTarget, and CreateInfoRenderpassRenderTarget. Note that the CreateInfoRenderpassRenderTarget is intended for use with the deprecated LegacyRenderPass. For all other render passes, use CreateInfoNode2DRenderTarget, or to acquire the composition targets use the CompositionManager.
Texture can optionally maintain CPU accessible copy of texture data. See CreateInfoHostCopy2D. for CPU accessible texture data details.
In order to create a texture, you must prepare Texture::CreateInfo structure and make sure it is valid using CreateInfo::validate(), then create the texture with Texture::create(). If texture creation parameters are not valid, Texture::create() will throw an exception, which can stop program execution.
Two dimensional textures can be created from Image or by specifying size, format and features. Cubemap textures can be created from six Images or by specifying size, format and features.
You must specify texture filtering, addressing mode (also known as wrap mode), and mipmap settings in Texture::CreateInfo before you create the texture. Two dimensional textures which are shown without scaling can be created with default texture creation parameters, which improve performance and reduce memory usage. If you show texture content with scaling, consider using linear filtering and prefiltered mipmaps to reduce aliasing, with some performance and memory cost.
Examples - Creating Textures with Kanzi C++ API
To create a two dimensional texture from image:
// This example shows how to create a texture from an image for use
// where texture content is shown without scaling. Texture will be
// created with default CreateInfo2D settings.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Texture::create()
// \see Texture::CreateInfo2D
BitmapImageUniquePtr image = generateImage(512, 512, 0, false);
TextureSharedPtr texture = Texture::create(domain, Texture::CreateInfo2D(kanzi::move(image)), "Texture");
To load image from file and create texture:
// Load an image file and create a texture out of it.
TextureSharedPtr texture = domain->getResourceManager()->acquireResource<Texture>(string("file://") + filePath);
To access the image data after you create a texture:
// Fill image data with opaque red.
unique_ptr<uint8_t[]> sourceData(new uint8_t[512 * 512 * 4]);
for (unsigned it = 0; it < 512 * 512 * 4; it += 4)
{
sourceData[it + 0] = 255u;
sourceData[it + 1] = 0u;
sourceData[it + 2] = 0u;
sourceData[it + 3] = 255u;
}
// Create an image.
BitmapImageUniquePtr image = BitmapImage::createFromMemory(512, 512, GraphicsFormatR8G8B8A8_UNORM, sourceData.get(), "image");
BitmapImage* imagePtr = image.get();
// Create a texture from the image. This texture keeps the ownership of the image.
// This means that the image is also automatically destroyed when the texture is destroyed.
Texture::CreateInfo2D createInfo(kanzi::move(image));
createInfo.memoryType = GPUResource::GpuAndRam;
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
// Get the host copy of the image you created. In this case the getHostCopyImage() returns a
// pointer that is identical to the variable imagePtr you created above.
BitmapImageSharedPtr hostCopyImage = texture->getHostCopyImage();
To create a two dimensional texture from image with custom sampler settings:
// This example shows how to create a texture from an image image for use
// where texture content is potentially shown with scaling.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Texture::create()
// \see Texture::CreateInfo2D
Texture::CreateInfo2D createInfo(kanzi::move(image));
// Adjust filter and mipmap settings to minimize aliasing.
createInfo.minificationFilter = Sampler::FilterLinear;
createInfo.magnificationFilter = Sampler::FilterLinear;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
// Get size and format from the image
createInfo.updateShapeAndFormatFromImages();
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
To create a cubemap texture from 6 face images:
// This example shows how to create a cube map texture from six images.
// This texture could be used in materials for 3D rendering.
// \see Image
// \see Texture::CreateInfoCubemap
// \see Texture::create()
Texture::CreateInfoCubemap createInfo(kanzi::move(images));
// Adjust filter and mipmap settings to minimize aliasing.
createInfo.minificationFilter = Sampler::FilterLinear;
createInfo.magnificationFilter = Sampler::FilterLinear;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
// Get size and format from the images.
createInfo.updateShapeAndFormatFromImages();
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
Examples - Loading textures with Kanzi C++ API using ResourceManager
To load texture with ResourceManager using file URL:
To load texture with ResourceManager:
Examples - Updating texture data with Kanzi C++ API
To update texture data of two dimensional texture base level image:
// Use Texture::setData() to update texture contents on two dimensional texture without host copy.
unsigned int width = 512;
unsigned int height = 512;
TextureSharedPtr texture = Texture::create(domain, Texture::CreateInfoHostCopy2D(width, height, GraphicsFormatR8G8B8_UNORM), "Texture");
// Set all texture data
{
vector<byte> data = generateTextureData(width, height, 0);
texture->setData(data.data());
}
// Set subrectangle
{
unsigned int updateWidth = width / 2;
unsigned int updateHeight = height / 2;
vector<byte> data = generateTextureData(updateWidth, updateHeight, 0);
unsigned int mipmapLevel = 0;
texture->setData(mipmapLevel, width - updateWidth, 0, updateWidth, updateHeight, data.data());
}
To update texture data of cubemap texture all mipmap level images:
// Use setData() to update texture contents on cubemap texture with host copy and mipmaps.
// All mipmap levels of all cubemap faces are set.
Texture::CreateInfo createInfo;
createInfo.type = TextureTypeCubeMap;
createInfo.width = 512;
createInfo.height = 512;
createInfo.format = GraphicsFormatR8G8B8_UNORM;
createInfo.features = GraphicsFormatFeatureSampledImage;
createInfo.memoryType = Texture::GpuAndRam;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
createInfo.mipmapLevelCount = calculateMipmapLevelCount(createInfo.width, createInfo.height);
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
unsigned int width = texture->getWidth();
unsigned int height = texture->getHeight();
for (unsigned int mipmapLevel = 0; mipmapLevel < createInfo.mipmapLevelCount; ++mipmapLevel)
{
for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
{
Surface::Face face = static_cast<Surface::Face>(faceIndex);
vector<byte> data = generateTextureData(width, height, faceIndex);
texture->setData(face, mipmapLevel, 0, 0, width, height, data.data());
}
width /= 2;
height /= 2;
}
Examples - Use texture as render target for node 2D or renderpass using Kanzi C++ API
To use texture as render target for 2D node:
// This example shows how to create a Texture and use it as a render target for a 2D node.
//
// Kanzi renders the node to the texture as specified with Node2D::setRenderTarget().
// Kanzi renders the node only to the texture as specified with Node2D::setOffscreenRendering().
//
// \see Node2D::RenderTargetProperty
// \see Node2D::OffscreenRenderingProperty
// \see Texture::CreateInfoNode2DRenderTarget
// \see Texture::create()
// Create a node tree.
ScreenSharedPtr screen = Screen::create(domain, "screen");
screen->attach();
// Create a node.
EmptyNode2DSharedPtr node = EmptyNode2D::create(domain, "node");
screen->addChild(node);
// Create a background brush for the node.
ColorBrushSharedPtr brush = ColorBrush::create(domain, "brush", ColorRGBA(0.4f, 0.4f, 0.9f, 1.0f));
node->setBackgroundBrush(brush);
// Create a render target texture for the node.
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(width, height, GraphicsFormatR8G8B8A8_UNORM);
TextureSharedPtr renderTarget = Texture::create(domain, textureCreateInfo, "texture");
node->setRenderTarget(renderTarget);
// Render only to the render target texture.
node->setOffscreenRendering(true);
// Render the node tree.
{
CompositionStack& compositionStack = renderer->getCompositionStack();
screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
screen->setArrangeTransform(Matrix3x3());
screen->layout();
compositionStack.pushComposition(0, screen->getAllocatedSize());
screen->render(*renderer, compositionStack);
compositionStack.popComposition();
}
screen->detach();
To use texture as render target for renderpass:
// This example shows how to create a Texture and use it as a render target
// for a render pass as used by a Viewport2D node.
//
// This texture could be used as content in Image2D nodes or texture brushes.
// This texture could also be used in materials for 3D rendering or material brushes.
//
// Renderpass will render a scene to the texture as specified with Renderpass::setRenderPassRenderTargetColor0().
// \see Renderpass
// \see Viewport2D
// \see Scene
// \see Texture::CreateInfoRenderpassRenderTarget
// \see Texture::create()
ScreenSharedPtr screen = Screen::create(domain, "screen");
screen->attach();
// Create Viewport2D node.
screen->addChild(viewport);
// Create Scene.
SceneSharedPtr scene = Scene::create(domain, "test scene");
viewport->setScene(scene);
// All scenes require a camera.
CameraSharedPtr camera = Camera::create(domain, "camera");
scene->addChild(camera);
scene->setCamera(camera);
// Create rendertarget texture.
Texture::CreateInfoRenderpassRenderTarget textureCreateInfo(width, height, GraphicsFormatR8G8B8A8_UNORM);
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Create renderpass prefab.
RenderPassTemplateSharedPtr clearTemplate = RenderPassTemplate::create(ClearRenderPass::getStaticMetaclass()->getName(), "clear render pass");
// There is no other content in the scene, but we do apply clear color.
ColorRGBA lightBlue(0.4f, 0.4f, 0.9f, 1.0f);
clearTemplate->addPropertyValue(ClearRenderPass::ClearColor0Property, Variant(lightBlue));
RenderPassTemplateSharedPtr drawTemplate = RenderPassTemplate::create(DrawObjectsRenderPass::getStaticMetaclass()->getName(), "draw render pass");
RenderPassTemplateSharedPtr rootTemplate = RenderPassTemplate::create(CompositionTargetRenderPass::getStaticMetaclass()->getName(), "composition render pass");
// Set texture to the composition target render pass.
rootTemplate->addPropertyValue(CompositionTargetRenderPass::CompositionTarget0Property, Variant(static_pointer_cast<Resource>(texture)));
rootTemplate->addChild(clearTemplate);
rootTemplate->addChild(drawTemplate);
RenderPassPrefabSharedPtr rootPrefab = RenderPassPrefab::create(domain, "test render pass prefab", rootTemplate);
viewport->setRenderPassPrefab(rootPrefab);
// Render the node tree.
{
CompositionStack& compositionStack = renderer3D->getCompositionStack();
screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
screen->setArrangeTransform(Matrix3x3());
screen->layout();
compositionStack.pushComposition(0, screen->getAllocatedSize());
screen->render(*renderer3D, compositionStack);
compositionStack.popComposition();
}
screen->detach();
Examples - Render to texture with framebuffer (OpenGL and OpenGL ES only) using Kanzi C++ API
To create a two dimensional texture and render to it through framebuffer:
// This example shows how to create a two dimensional texture without mipmaps and render to it with framebuffer.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Framebuffer
// \see Texture::CreateInfo2D
// \see Texture::create()
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterLinear;
// Add depthStencil renderbuffer, for depth test to work. In this example
textureCreateInfo.depthStencilFormat = renderer->getDepthStencilFormatForRenderbuffer(true, false);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render something to framebuffer. Here we just clear the texture.
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
// Fill texture with a color
renderer->resetClearTarget();
renderer->addClearColor(0, 0.5f, 0.6f, 0.7f, 1.0f);
renderer->clear();
renderer->resetClearTarget();
renderer->resetActiveFramebuffer();
To create a two dimensional texture with mipmaps and render to it through framebuffer:
// This example shows how to create a two dimensional texture with mipmaps
// and render to it with a framebuffer.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Framebuffer
// \see Texture::CreateInfo2D
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterNearest;
// Specify that texture needs to be created with mipmaps
textureCreateInfo.mipmapMode = Sampler::MipmapModeLinear;
textureCreateInfo.mipmapLevelCount = calculateMipmapLevelCount(textureCreateInfo.width, textureCreateInfo.height);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render something to framebuffer. Here we just clear the base level image of the texture.
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
renderer->resetClearTarget();
renderer->addClearColor(0, 0.5f, 0.6f, 0.7f, 1.0f);
renderer->clear();
renderer->resetClearTarget();
renderer->resetActiveFramebuffer();
// Generate mipmaps for texture. Without this, remaining mipmap level images would have undefined content.
texture->generateMipmaps();
To create a cubemap texture with mipmaps and render to it through framebuffers:
// This example shows how to create a cubemap texture with mipmpas and render to it with a set of framebuffers.
// This texture could be used in materials for 3D rendering.
// Create texture create info.
Texture::CreateInfo textureCreateInfo;
// Set the texture settings.
textureCreateInfo.width = 512;
textureCreateInfo.height = 512;
textureCreateInfo.format = GraphicsFormatR8G8B8A8_UNORM;
// Specify that a cubemap texture is to be created
textureCreateInfo.type = TextureTypeCubeMap;
// Specify render target mode for the cube map texture.
textureCreateInfo.renderTargetMode = RenderTargetModeInternal;
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterLinear;
// Specify that texture has mipmaps
textureCreateInfo.mipmapMode = Sampler::MipmapModeLinear;
textureCreateInfo.mipmapLevelCount = calculateMipmapLevelCount(textureCreateInfo.width, textureCreateInfo.height);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render to all cubemap faces
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
{
// Bind the current side of the texture for rendering.
{
renderer->framebufferTexture2D(targetImage, Surface::APIAttachmentColor0, texture->getNativeHandle(), 0, 1);
}
// Come up with content for each face; Fill with six shades of gray.
float relativeFace = static_cast<float>(faceIndex) / 5.0f;
renderer->resetClearTarget();
renderer->addClearColor(0, relativeFace, relativeFace, relativeFace, 1.0f);
renderer->clear();
renderer->resetClearTarget();
}
renderer->resetActiveFramebuffer();
// Generate mipmaps for texture. Without this, remaining mipmap level images would have undefined content.
texture->generateMipmaps();
Constructor & Destructor Documentation
◆ Texture() [1/2]
|
explicitprotected |
Creates texture from CreateInfo.
Texture will be deployed, if createInfo memory type includes Gpu.
◆ Texture() [2/2]
|
explicitprotected |
Creates texture from an existing GL object handle.
Caller must also provide texture format, and size. glHandle should be a valid GL texture object. Optionally, kanzi::Texture can take ownership of the provided GL texture object, in which case destroying kanzi::Texture will also destroy the GL texture object. If ownership is not passed to kanzi::Texture, then GL texture must be deleted after kanzi::Texture. Do not delete GL texture object while kanzi::Texture exists.
- Note
- Caller should always provide accurate information in format, mipmapLevelCount, width and height.
- Parameters
-
domain Domain for texture. type Texture type. glHandle Pre-existing valid GL texture object name. format Format of the texture. mipmapLevelCount Mipmap level count of the texture. width Width of the texture. height Height of the texture. takeOwnership Should kanzi::Texture take ownership of provided GL texture object name Name
Member Function Documentation
◆ create() [1/2]
|
static |
Creates a texture with specified texture creation parameters.
In order to create a texture, you will need a CreateInfo structure that is filled with valid combination of texture creation parameters. You can use CreateInfo, CreateInfo2D, CreateInfoHostCopy2D, CreateInfoNode2DRenderTarget, CreateInfoRenderpassRenderTarget and CreateInfoCubemap constructors to create and initialize a texture creation parameter structure. After calling the constructor you can fine tune texture creation parameters.
You can check that parameters are valid by calling CreateInfo::validate().
If you pass CreateInfo that is not valid, Texture::create() will throw an exception and program execution may will terminate. To avoid exceptions for recoverable errors, use Renderer::adjust() on the create info prior to calling this function.
If createInfo memory type includes Gpu, texture will be deployed.
If createInfo memory type includes Ram, host copy of texture data will be made accessible. Otherwise, texture host copy will not be accessible.
- Note
- create() takes ownership of images you pass in the create info. You must not delete images that you pass to Texture::create() in createInfos. You must immediately discard any CreateInfo which contains images after first call to create(). The images in createInfo are no longer valid, and such CreateInfo cannot be reused.
- Parameters
-
domain Domain for the texture. createInfo Texture creation parameters. name Name for the texture.
- Returns
- Texture shared pointer.
◆ create() [2/2]
|
static |
Creates texture from a pre-existing GL texture object.
Optionally, kanzi::Texture can take ownership of the provided GL texture object, in which case destroying kanzi::Texture will also destroy the GL texture object. If ownership is not passed to kanzi::Texture, then GL texture must be deleted after kanzi::Texture. Do not delete GL texture object while kanzi::Texture exists.
- Note
- Caller should always provide accurate information in format, mipmapLevelCount, width and height.
- Parameters
-
domain Domain. type Texture type. nativeHandle Pre-existing native handle that identifies a valid GL texture object. takeOwnership If true, texture will take ownership of the native resource (GL texture object). format Format of the texture. mipmapLevelCount Number of mipmap levels in the texture. width Width of the texture. height Height of the texture. name Name.
- Returns
- Texture shared pointer.
◆ getSampler()
◆ getType()
| TextureType kanzi::Texture::getType | ( | ) | const |
Returns type of the texture.
◆ getNativeDeploymentTarget()
| NativeDeploymentTarget kanzi::Texture::getNativeDeploymentTarget | ( | ) | const |
Returns the native deployment target.
◆ reattachFramebuffer() [1/3]
| void kanzi::Texture::reattachFramebuffer | ( | ) |
Reattaches the internal framebuffer object.
Only renderbuffers and the color texture within the texture object will be used.
◆ reattachFramebuffer() [2/3]
| void kanzi::Texture::reattachFramebuffer | ( | RenderbufferSharedPtr | colorRenderbuffer | ) |
Reattaches the internal framebuffer object and includes the renderbuffer given as parameter.
The texture does not take ownership of the renderbuffer. The texture must not have an internal color texture.
- Parameters
-
colorRenderbuffer Renderbuffer to use as the color target in the framebuffer.
◆ reattachFramebuffer() [3/3]
| void kanzi::Texture::reattachFramebuffer | ( | TextureSharedPtr | depthTexture | ) |
Reattaches the internal framebuffer object and includes the depth texture given as parameter.
The texture does not take ownership of the depth texture. The texture must not have an internal depth render buffer.
- Parameters
-
depthTexture Depth texture to use as the depth target in the framebuffer.
◆ generateMipmaps()
| void kanzi::Texture::generateMipmaps | ( | ) |
Generates the mipmaps from the base level image.
This reads from Gpu texture data from the base level images, and only updates Gpu texture data of the remaining mipmap images. If texture has host copy data, it remains unchanged.
◆ setData() [1/3]
| void kanzi::Texture::setData | ( | Face | face, |
| unsigned int | mipmapLevel, | ||
| unsigned int | x, | ||
| unsigned int | y, | ||
| unsigned int | width, | ||
| unsigned int | height, | ||
| const kanzi::byte * | data ) |
Sets the texture data for the specified area in a texture.
The texture data is updated to the GPU memory, and to the CPU accessible copy of the texture, if the texture is created with such storage.
- Note
- The format of the data must match the format of the texture.
- Parameters
-
face Which texture face to update. mipmapLevel Which mipmap level to update. x,y,width,height Specifies the rectangle to update. data Texture data.
◆ setData() [2/3]
| void kanzi::Texture::setData | ( | unsigned int | mipmapLevel, |
| unsigned int | x, | ||
| unsigned int | y, | ||
| unsigned int | width, | ||
| unsigned int | height, | ||
| const kanzi::byte * | data ) |
Sets the texture data for the specified area in the texture.
The texture data is updated to the GPU memory, and to the CPU accessible copy of the texture, if the texture is created with such storage.
- Note
- The format of the data must match the format of the texture.
- Parameters
-
mipmapLevel Which mip level to update. x,y,width,height Specifies the rectangle to update. data Texture data.
◆ setData() [3/3]
| void kanzi::Texture::setData | ( | const kanzi::byte * | data | ) |
Sets the texture data for base level of a non-cubemap texture.
- Parameters
-
data Texture data.
◆ getNativeHandle()
| NativeTextureHandle kanzi::Texture::getNativeHandle | ( | ) | const |
Gets native texture handle for the texture.
- Returns
- Native texture handle.
◆ getNativeFramebufferHandle()
| NativeFramebufferHandle kanzi::Texture::getNativeFramebufferHandle | ( | ) | const |
Gets native framebuffer handle for the texture.
- Note
- Only textures created with RenderTargetMode set to RenderTargetInternal will have native framebuffer handle.
- Returns
- Native framebuffer handle, or 0 if texture was created with rendertarget mode other than RenderTargetInternal.
◆ getDepthStencilFormat()
|
inline |
Returns depth/stencil format of the texture.
- Note
- Only textures created with RenderTargetMode set to RenderTargetInternal will have depth stencil buffer.
- Returns
- Graphics format of depth stencil buffer, or GraphicsFormatNone if texture does not have depth stencil buffer.
◆ getDepthStencilRenderbuffer()
|
inline |
Returns internal depth/stencil renderbuffer.
- Returns
- Renderbuffer created internally for the texture, or nullptr.
◆ getHostCopyImage() [1/2]
| BitmapImageSharedPtr kanzi::Texture::getHostCopyImage | ( | Face | face, |
| unsigned int | slice ) const |
Returns the host-side memory copy of texture data as an image, if available.
Returns as an image the copy of the host-side memory of the texture data, but does not create a copy of that image. Use this function only to retrieve data that was sent to the GPU from the CPU memory. To retrieve data rendered to a texture by the GPU use captureScreenToImage().
- Parameters
-
face The texture face for which you want to get the data. For single textures, this value is FaceDefault. For cubemap textures, use a valid face for the texture. For example, FacePositiveX, or FaceNegativeZ. If you try to access an invalid texture face, the function throws an exception. slice The texture slice for which you want to get the data. Slice applies to array and 3D textures. Currently this parameter must always be 0. If you access an invalid texture slice, the function throws an exception.
- Returns
- When you create a texture with the MemoryType property set to GpuAndRam or RamOnly, returns the host-side image uploaded to to the GPU. If you create a texture with the MemoryType property set to GpuOnly, or try to retrieve a composition target texture, returns a null pointer.
◆ getHostCopyImage() [2/2]
| BitmapImageSharedPtr kanzi::Texture::getHostCopyImage | ( | ) | const |
Returns the host-side memory copy of a non-cubemap texture, if available.
Returns as an image the copy of the host-side memory of the default face of a single texture data, but it does not create a copy of that image.
- Returns
- When you create a texture with the MemoryType property set to GpuAndRam or RamOnly, returns the host-side image uploaded to to the GPU. If you create a texture with the MemoryType property set to GpuOnly, try to retrieve a composition target texture, or a face from a cubemap texture, returns a null pointer.
◆ getRenderTargetMode()
|
inline |
◆ resize()
Changes the size of the texture.
Texture contents are undefined after resizing, user should assume they are destroyed. Specifying size identical to current size will cause resizing not to happen.
NOTE: Internal API and subject to change or removal.
- Parameters
-
width New width. height New height.
◆ getWidthDivisor()
Gets width divisor for automatic sizes.
- Returns
- Width divisor.
◆ setWidthDivisor()
Sets the wight divisor.
- Parameters
-
divisor New width divisor.
◆ hasAutomaticWidth()
|
inline |
Indicates whether width is or should be automatically calculated.
- Returns
- If width should be automatically calculated true, otherwise false.
◆ getHeightDivisor()
Gets height divisor for automatic sizes.
- Returns
- Height divisor.
◆ setHeightDivisor()
Sets the height divisor.
- Parameters
-
divisor New height divisor.
◆ hasAutomaticHeight()
|
inline |
Indicates whether height is or should be automatically calculated.
- Returns
- If height should be automatically calculated true, otherwise false.
◆ createLoadTask()
|
static |
◆ createGenericFileLoadTask()
|
static |
◆ recreate()
| void kanzi::Texture::recreate | ( | CreateInfo & | createInfo | ) |
Validates the CreateInfo texture descriptor, creates a new texture and swaps it in place.
- Parameters
-
createInfo The texture descriptor.
◆ resolveMSAA()
Resolves the internal multisample anti-aliasing renderbuffer to a single sample texture, if necessary.
This is required after the rendering is complete if more than one sample is requested and the target device does not support implicit MSAA. In this case, Kanzi uses the internal renderbuffer.
- Parameters
-
renderer Renderer.
- Since
- Kanzi 3.9.7
◆ reloadOverride()
|
overrideprotectedvirtual |
Resource::reloadOverride() implementation.
Reimplemented from kanzi::Resource.
◆ reloadFromKzbOverride()
|
overrideprotectedvirtual |
Resource::reloadFromKzbOverride() implementation.
Reimplemented from kanzi::Resource.
◆ reloadFromFileOverride()
|
overrideprotectedvirtual |
Resource::reloadFromFileOverride() implementation.
Reimplemented from kanzi::Resource.
◆ getCPUMemoryUsageOverride()
Resource::getCPUMemoryUsageOverride() implementation.
Reimplemented from kanzi::Resource.
◆ invalidateOverride()
|
overrideprotectedvirtual |
GPUResource::invalidateOverride() implementation.
Reimplemented from kanzi::GPUResource.
◆ destroyOverride()
|
overrideprotectedvirtual |
GPUResource::destroyOverride() implementation.
Reimplemented from kanzi::GPUResource.
◆ isDeployedOverride()
|
overrideprotectedvirtual |
GpuResource::isDeployed() implementation.
Implements kanzi::GPUResource.
◆ getGPUMemoryUsageOverride()
GpuResource::getGPUMemoryUsageOverride() implementation.
Reimplemented from kanzi::GPUResource.
◆ attachOverride()
|
overrideprotectedvirtual |
Surface::attachOverride() implementation.
Implements kanzi::Surface.
◆ getFormatOverride()
|
overrideprotectedvirtual |
Surface::getFormatOverride() implementation.
Implements kanzi::Surface.
◆ getFeaturesOverride()
Surface::getFeaturesOverride() implementation.
Implements kanzi::Surface.
◆ getRenderTargetSampleCountOverride()
Surface::getRenderTargetSampleCountOverride() implementation.
Implements kanzi::Surface.
◆ getWidthOverride()
Surface::getWidthOverride() implementation.
Implements kanzi::Surface.
◆ getHeightOverride()
Surface::getHeightOverride() implementation.
Implements kanzi::Surface.
◆ getSliceCountOverride()
Surface::getSliceCountOverride() implementation.
Implements kanzi::Surface.
◆ getFaceCountOverride()
Surface::getFaceCountOverride() implementation.
Implements kanzi::Surface.
◆ getMipmapLevelCountOverride()
Surface::getMipmapLevelCountOverride() implementation.
Implements kanzi::Surface.
◆ makeHostCopyImages()
|
staticprotected |
Helper function to allocate host images.
There are three cases:
- Texture is created with GpuOnly memory type, empty vector will be returned.
- Texture is created with RamOnly or GpuAndRam memory type, and create info contains images. A vector containing those images from create info will be returned.
- Texture is created with RamOnly or GpuAndRam memory type, create info did not contain images. Returns a vector that contains newly allocated images.
- Parameters
-
createInfo Texture create info.
- Returns
- Vector of images. It will be empty if texture memory type is GpuOnly, otherwise it will have images from createInfo if it has images, and if not, it will return newly allocated images.
◆ makeTexture()
|
staticprotected |
◆ makeFramebuffer()
|
staticprotected |
Helper function to create GL framebuffer object.
Only dummy handle will be created if create info specifies RamOnly texture, or if texture rendertarget mode is not RenderTargetModeInternal.
- Returns
- Framebuffer handle.
◆ deployImages()
|
protected |
◆ deployInternalFramebuffers()
|
protected |
Helper function to setup GL framebuffer and renderbuffer state Called as part of texture construction.
Texture internal variables must already be initialized.
- Parameters
-
renderer Renderer. colorRenderbuffer Color renderbuffer not owned by the texture to attach. depthTexture Depth texture not owned by this texture to attach.
Friends And Related Symbol Documentation
◆ ResourceManager
|
friend |
◆ swap
The documentation for this class was generated from the following file:
- kanzi/core.ui/platform/graphics_backend/gl/texture.hpp