/**
- * @brief BufferImage represents an image resource that can be added to ImageActors.
+ * @brief BufferImage represents an image resource as a pixel data buffer
* Its pixel buffer data is provided by the application developer.
*
- * Care should be taken with pixel data allocated by the application,
- * as the data is copied to GL both when the image is added to the
- * stage and after a call to Update(). In both of these cases, a
- * SignalUploaded will be sent to the application confirming that the
- * operation has completed.
- *
- * The application can free the pixel data after receiving a
- * SignalUploaded.
- *
- * Similarly, once the image is on stage (i.e. it's being used by an
- * ImageActor that is on stage), the application should only write to
- * the buffer after receiving a SignalUploaded, then call Update()
- * once the write is finished. This avoids the pixel data being changed
- * whilst it's being copied to GL. Writing to the buffer without waiting
- * for the signal will likely result in visible tearing.
- *
* If the pixel format of the pixel buffer contains an alpha channel,
* then the image is considered to be have transparent pixels without
* regard for the actual content of the channel, and will be blended.
*
- * If the image is opaque and blending is not required, then the user
- * should call ImageActor::SetUseImageAlpha(false) on the containing actor.
*/
class DALI_IMPORT_API BufferImage : public Image
{
/**
* @brief Create a new BufferImage.
*
+ * @deprecated DALi 1.1.3, use New( unsigned int width, unsigned int height ) instead.
+ *
* Also a pixel buffer for image data is allocated.
* Dali has ownership of the buffer.
* For better performance and portability use power of two dimensions.
/**
* @brief Create a new BufferImage, which uses an external data source.
*
+ * @deprecated DALi 1.1.3, use New( PixelBuffer* pixelBuffer, unsigned int width, unsigned int height ) instead.
+ *
* The PixelBuffer has to be allocated by application.
*
* The application holds ownership of the buffer. It must not
return image;
}
+EncodedBufferImage EncodedBufferImage::New( const uint8_t * const encodedImage,
+ std::size_t encodedImageByteCount,
+ ImageDimensions size, FittingMode::Type fittingMode, SamplingMode::Type samplingMode,
+ bool orientationCorrection )
+{
+ Internal::EncodedBufferImagePtr internal = Internal::EncodedBufferImage::New( encodedImage, encodedImageByteCount, size, fittingMode, samplingMode, orientationCorrection, Dali::Image::NEVER );
+ EncodedBufferImage image(internal.Get());
+ return image;
+}
+
EncodedBufferImage EncodedBufferImage::DownCast( BaseHandle handle )
{
return EncodedBufferImage( dynamic_cast<Dali::Internal::EncodedBufferImage*>(handle.GetObjectPtr()) );
/**
- * @brief EncodedBufferImage represents an image resource that can be added to
- * ImageActors.
+ * @brief EncodedBufferImage represents a Image as a buffer of encoded pixel data.
*
* A memory buffer of encoded image data is provided by the application and
* decoded asynchronously on a background thread to fill the image's
/**
* @brief Create an initialised image object from an encoded image buffer in memory.
*
- * The image will be created eagerly using LoadPolicy::Immediate.
- * The function is non-blocking and returns immediately while the image
- * decoding happens on a background thread.
+ * @deprecated DALi 1.1.3 use New(const uint8_t* const, std::size_t,ImageDimensions,FittingMode::Type,SamplingMode::Type,bool) instead.
+ *
* @param [in] encodedImage The encoded bytes of an image, in a supported
* image format such as PNG, JPEG, GIF, BMP, KTX, ICO, and WBMP, organised
* exactly as it would be as a file in the filesystem.
* @param [in] size The width and height to fit the loaded image to.
* @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
* @param [in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size.
- * @param [in] releasePol The ReleasePolicy to apply to Image. If the Unused
+ * @param [in] releasePol The ReleasePolicy to apply to Image.
* @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
* policy is set, a reload will not be possible, so the Image should never be
* used once all actors using it have gone off-stage.
* @return A handle to a newly allocated object.
*/
- static EncodedBufferImage New( const uint8_t * const encodedImage, std::size_t encodedImageByteCount, ImageDimensions size, FittingMode::Type fittingMode, SamplingMode::Type samplingMode, ReleasePolicy releasePol = Image::NEVER, bool orientationCorrection = true );
+ static EncodedBufferImage New( const uint8_t * const encodedImage, std::size_t encodedImageByteCount, ImageDimensions size, FittingMode::Type fittingMode, SamplingMode::Type samplingMode, ReleasePolicy releasePol, bool orientationCorrection = true );
/**
* @brief Create an initialised image object from an encoded image buffer in memory.
*
- * The image will be created eagerly using LoadPolicy::Immediate.
- * The function is non-blocking and returns immediately while the image
- * decoding happens on a background thread.
* @param [in] encodedImage The encoded bytes of an image, in a supported
* image format such as PNG, JPEG, GIF, BMP, KTX, ICO, and WBMP, organised
* exactly as it would be as a file in the filesystem.
static EncodedBufferImage New( const uint8_t * const encodedImage, std::size_t encodedImageByteCount );
/**
+ * @brief Create an initialised image object from an encoded image buffer in memory.
+ *
+ * @param [in] encodedImage The encoded bytes of an image, in a supported
+ * image format such as PNG, JPEG, GIF, BMP, KTX, ICO, and WBMP, organised
+ * exactly as it would be as a file in the filesystem.
+ * The caller retains ownership of this buffer and is free to modify or
+ * discard it as soon as the function returns.
+ * @param [in] encodedImageByteCount The size in bytes of the buffer pointed to
+ * by encodedImage.
+ * @param [in] size The width and height to fit the loaded image to.
+ * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
+ * @param [in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size.
+ * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
+ * policy is set, a reload will not be possible, so the Image should never be
+ * used once all actors using it have gone off-stage.
+ * @return A handle to a newly allocated object.
+ */
+ static EncodedBufferImage New( const uint8_t * const encodedImage, std::size_t encodedImageByteCount, ImageDimensions size, FittingMode::Type fittingMode, SamplingMode::Type samplingMode, bool orientationCorrection = true );
+
+ /**
* @brief Downcast an Object handle to EncodedBufferImage.
*
* If handle points to a EncodedBufferImage the
}
/**
- * @brief FrameBufferImage represents a GLES Frame Buffer Object and contains the result
- * of an 'off screen' render pass of a RenderTask.
- * The FrameBufferImage can then be used with an ImageActor (with optional shader
- * effects) and rendered to the screen.
+ * @brief FrameBufferImage represents a Open GL ES Frame Buffer Object
+ * It contains the result of an 'off screen' render pass of a RenderTask.
+ * The FrameBufferImage can then be used for rendering to the screen.
*/
class DALI_IMPORT_API FrameBufferImage : public Image
{
* @brief Create a new FrameBufferImage.
*
* The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
- * The ReleasePolicy defaults to Dali::Image::Never.
+ *
* @param [in] width The width in pixels. Setting to zero will use the width of the stage.
* @param [in] height The height in pixels. Setting to zero will use the height of the stage.
* @param [in] pixelFormat The pixel format (rgba 32 bit by default)
/**
* @brief Create a new FrameBufferImage.
*
+ * @deprecated DALi 1.1.3 use New() instead.
+ *
* The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
* @param [in] width The width in pixels. Setting to zero will use the width of the stage.
* @param [in] height The height in pixels. Setting to zero will use the height of the stage.
* @param [in] releasePolicy The ReleasePolicy to apply to the FrameBufferImage.
* @param [in] bufferFormat The format of the buffers that are going to be created for the FBO, (COLOR and DEPTH buffer as default)
*
- * Note that there is no need for a LoadPolicy - by definition it is always OnDemand, since there is no point in the FrameBufferImage existing unless someone is rendering to
- * it, or it is being used as an input (e.g. ShaderEffect / ImageActor).
- *
* @post When the FrameBufferImage is first used as a render target, an exception may be thrown if pixelFormat is not supported on the hardware platform.
* @return A handle to a new instance of a FrameBufferImage.
*/
* The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
* @param [in] image The native image.
*
- * Note that there is no need for a LoadPolicy - by definition it is always OnDemand, since there is no point in the FrameBufferImage existing unless someone is rendering to
- * it, or it is being used as an input (e.g. ShaderEffect / ImageActor).
- *
* @post When the FrameBufferImage is first used as a render target, an exception may be thrown if the NativeImage cannot be mapped to a texture.
* @return A handle to a new instance of a FrameBufferImage.
*/
/**
* @brief Create a new FrameBufferImage.
*
+ * @deprecated DALi 1.1.3 use New( NativeImageInterface& ) instead.
+ *
* The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
* @param [in] image The native image.
* @param [in] releasePolicy The ReleasePolicy to apply to the FrameBufferImage.
*
- * Note that there is no need for a LoadPolicy - by definition it is always OnDemand, since there is no point in the FrameBufferImage existing unless someone is rendering to
- * it, or it is being used as an input (e.g. ShaderEffect / ImageActor).
- *
* @post When the FrameBufferImage is first used as a render target, an exception may be thrown if the NativeImage cannot be mapped to a texture.
* @return A handle to a new instance of a FrameBufferImage.
*/
}
/**
- * @brief An Image object represents an image resource that can be added to ImageActors.
+ * @brief An Image object represents an image resource that can be used for rendering
*
- * Image objects can be shared between ImageActors. This is practical if you have a visual element on screen
- * which is repeatedly used. An example would be a button background image.
- * The image resource is discarded when all ImageActors using the Image object are discarded or in case they
- * were created with ReleasePolicy::Unused, taken off stage.
- * Note: if a resource was shared between Image objects it exists until its last reference is gone.
+ * Image objects can be shared between Actors. This is practical if you have a visual element on screen
+ * which is repeatedly used.
*
* Image objects are responsible for the underlying resource's lifetime.
- *
- * <i>ReleasePolicies</i>
- * - Unused: release resource once ImageActor using it is taken off stage.
- * - Never: keep resource alive until Image object is thrown away.
- *
- * <i>Resolution of conflicting policies</i>
- * If the same image is created more than once with conflicting policies, ReleasePolicy "Never" overrides "Unused".
+ * Note: if a resource was shared between Image objects it exists until its last reference is gone.
*
* Signals
* | %Signal Name | Method |
class DALI_IMPORT_API Image : public BaseHandle
{
public:
- /**
- * @brief Resource management options.
- */
/**
* @brief ReleasePolicy controls the way images are deleted from memory.
+ * @deprecated DALi 1.1.3 Image resource is relased as soon as last handle is released
*/
enum ReleasePolicy
{
/**
* @brief Return resource release policy.
+ * @deprecated DALi 1.1.3
*
* @return resource release policy
*/
}
/**
- * @brief NativeImage represents an image resource that can be added to ImageActors.
- * Its data is provided by native resources, such as shared bitmap memory or pixmap from X11 or ECORE-X11, etc.
+ * @brief NativeImage represents a platform specific image resource.
+ * Its data is provided by native resources, such as shared bitmap memory or pixmap.
*/
class DALI_IMPORT_API NativeImage : public Image
{
}
/**
- * @brief NinePatchImage represents an image resource that can be added to ImageActors.
+ * @brief NinePatchImage represents a stretchable image resource
+ *
* It contains a bitmap that is synchronously loaded from the file system that contains
* a 9 patch border - a 1 pixel border that describes the stretch borders and the child
* area.
*
* <h3>ResourceImage Loading</h3>
*
- * When the ResourceImage is created, resource loading will be attempted unless
- * the ResourceImage is created with IMMEDIATE loading policy or a compatible resource is found in cache.
- * In case of loading images ON_DEMAND, resource loading will only be attempted if the associated ImageActor
- * is put on Stage.
+ * When the ResourceImage is created, resource loading will be attempted unless a compatible resource is found in cache.
* Scaling of images to a desired smaller size can be requested by providing desired dimensions,
* scaling mode and filter mode to to ResourceImage::New().
*
- * <i>LoadPolicies</i>
- * - IMMEDIATE: acquire image resource when creating ResourceImage.
- * - ON_DEMAND: only load in case the associated ImageActor is put on Stage
- *
- * <i>Resolution of conflicting policies</i>
- * If the same image is created more than once with conflicting policies, LoadPolicy "IMMEDIATE" overrides "ON_DEMAND".
- *
* <i>Custom load requests</i>
* Size, scaling mode, filter mode, and orientation compensation can be set when requesting an image.
*
* <i>Compatible resources</i>
*
- * Before loading a new ResourceImage the internal image resource cache is checked by dali.
+ * Before loading a new ResourceImage the internal image resource cache is checked by DALi.
* If there is an image already loaded in memory and is deemed "compatible" with the requested image,
* that resource is reused.
* This happens for example if a loaded image exists with the same URL, scaling and filtering modes,
*
* The same request used on creating the ResourceImage is re-issued when reloading images.
* If the file changed since the last load operation, this might result in a different resource.
- * Reload only takes effect if both of these conditions apply:
- * - The ResourceImage has already finished loading
- * - The ResourceImage is either on Stage or using IMMEDIATE load policy
+ * Reload only takes effect if the ResourceImage has already finished loading
*
* Signals
* | %Signal Name | Method |
class DALI_IMPORT_API ResourceImage : public Image
{
public:
- /**
- * @brief Resource management options.
- */
/**
* @brief LoadPolicy controls the way images are loaded into memory.
+ * @deprecated DALi 1.1.3 Image loading starts immediately in the frame when then ResourceImage object is created
*/
enum LoadPolicy
{
/**
* @brief Create an initialised ResourceImage object.
*
+ * @deprecated DALi 1.1.3 use New( const std::string& url ) instead.
+ *
* @param [in] url The URL of the image file to use.
* @param [in] loadPol The LoadPolicy to apply when loading the image resource.
* @param [in] releasePol The ReleasePolicy to apply to Image.
/**
* @brief Create an initialised ResourceImage object.
*
+ * @deprecated DALi 1.1.3 use New( const std::string& url, ImageDimensions size ) instead.
+ *
* @param [in] url The URL of the image file to use.
* @param [in] loadPol The LoadPolicy to apply when loading the image resource.
* @param [in] releasePol The ReleasePolicy to apply to Image.
/**
* @brief Return load policy.
+ * @deprecated DALi 1.1.3
*
* @return resource load policy
*/