2d-sliced: add _new_from_file/data/bitmap apis

This adds cogl_texture_2d_sliced_new_from_bitmap/data/file apis in
preparation for removing the cogl_texture_new_from_bitmap/file apis that
are considered a bit too magic, but we don't want to loose the
convenience they have.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

1 files changed, 165 insertions, 0 deletions

diff --git a/cogl/cogl-texture-2d-sliced.h b/cogl/cogl-texture-2d-sliced.h
index e26157e6..882bdd68 100644
--- a/cogl/cogl-texture-2d-sliced.h
+++ b/cogl/cogl-texture-2d-sliced.h
@@ -114,6 +114,171 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
                                       CoglPixelFormat internal_format);
 
 /**
+ * cogl_texture_2d_sliced_new_from_file:
+ * @ctx: A #CoglContext
+ * @filename: the file to load
+ * @max_waste: The threshold of how wide a strip of wasted texels
+ *             are allowed along the right and bottom textures before
+ *             they must be sliced to reduce the amount of waste. A
+ *             negative can be passed to disable slicing.
+ * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    format similar to the format of the source data will be used. The
+ *    default blending equations of Cogl expect premultiplied color data;
+ *    the main use of passing a non-premultiplied format here is if you
+ *    have non-premultiplied source data and are going to adjust the blend
+ *    mode (see cogl_material_set_blend()) or use the data for something
+ *    other than straight blending.
+ * @error: A #CoglError to catch exceptional errors or %NULL
+ *
+ * Creates a #CoglTexture2DSliced from an image file.
+ *
+ * A #CoglTexture2DSliced may internally be comprised of 1 or more
+ * #CoglTexture2D textures depending on GPU limitations.  For example
+ * if the GPU only supports power-of-two sized textures then a sliced
+ * texture will turn a non-power-of-two size into a combination of
+ * smaller power-of-two sized textures. If the requested texture size
+ * is larger than is supported by the hardware then the texture will
+ * be sliced into smaller textures that can be accessed by the
+ * hardware.
+ *
+ * @max_waste is used as a threshold for recursively slicing the
+ * right-most or bottom-most slices into smaller sizes until the
+ * wasted padding at the bottom and right of the textures is less than
+ * specified. A negative @max_waste will disable slicing.
+ *
+ * <note>It's possible for the allocation of a sliced texture to fail
+ * later due to impossible slicing constraints if a negative
+ * @max_waste value is given. If the given virtual texture size is
+ * larger than is supported by the hardware but slicing is disabled
+ * the texture size would be too large to handle.</note>
+ *
+ * Return value: A newly created #CoglTexture2DSliced or %NULL on
+ *               failure and @error will be updated.
+ *
+ * Since: 1.16
+ */
+CoglTexture2DSliced *
+cogl_texture_2d_sliced_new_from_file (CoglContext *ctx,
+                                      const char *filename,
+                                      int max_waste,
+                                      CoglPixelFormat internal_format,
+                                      CoglError **error);
+
+/**
+ * cogl_texture_2d_sliced_new_from_data:
+ * @width: width of texture in pixels
+ * @height: height of texture in pixels
+ * @format: the #CoglPixelFormat the buffer is stored in in RAM
+ * @max_waste: The threshold of how wide a strip of wasted texels
+ *             are allowed along the right and bottom textures before
+ *             they must be sliced to reduce the amount of waste. A
+ *             negative can be passed to disable slicing.
+ * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    format similar to the format of the source data will be used. The
+ *    default blending equations of Cogl expect premultiplied color data;
+ *    the main use of passing a non-premultiplied format here is if you
+ *    have non-premultiplied source data and are going to adjust the blend
+ *    mode (see cogl_material_set_blend()) or use the data for something
+ *    other than straight blending.
+ * @rowstride: the memory offset in bytes between the start of each
+ *    row in @data. A value of 0 will make Cogl automatically
+ *    calculate @rowstride from @width and @format.
+ * @data: pointer the memory region where the source buffer resides
+ * @error: A #CoglError to catch exceptional errors or %NULL
+ *
+ * Creates a new #CoglTexture2DSliced texture based on data residing
+ * in memory.
+ *
+ * A #CoglTexture2DSliced may internally be comprised of 1 or more
+ * #CoglTexture2D textures depending on GPU limitations.  For example
+ * if the GPU only supports power-of-two sized textures then a sliced
+ * texture will turn a non-power-of-two size into a combination of
+ * smaller power-of-two sized textures. If the requested texture size
+ * is larger than is supported by the hardware then the texture will
+ * be sliced into smaller textures that can be accessed by the
+ * hardware.
+ *
+ * @max_waste is used as a threshold for recursively slicing the
+ * right-most or bottom-most slices into smaller sizes until the
+ * wasted padding at the bottom and right of the textures is less than
+ * specified. A negative @max_waste will disable slicing.
+ *
+ * <note>It's possible for the allocation of a sliced texture to fail
+ * later due to impossible slicing constraints if a negative
+ * @max_waste value is given. If the given virtual texture size is
+ * larger than is supported by the hardware but slicing is disabled
+ * the texture size would be too large to handle.</note>
+ *
+ * Return value: A newly created #CoglTexture2DSliced or %NULL on
+ *               failure and @error will be updated.
+ *
+ * Since: 1.16
+ */
+CoglTexture2DSliced *
+cogl_texture_2d_sliced_new_from_data (CoglContext *ctx,
+                                      int width,
+                                      int height,
+                                      int max_waste,
+                                      CoglPixelFormat format,
+                                      CoglPixelFormat internal_format,
+                                      int rowstride,
+                                      const uint8_t *data,
+                                      CoglError **error);
+
+/**
+ * cogl_texture_2d_sliced_new_from_bitmap:
+ * @bitmap: A #CoglBitmap
+ * @max_waste: The threshold of how wide a strip of wasted texels
+ *             are allowed along the right and bottom textures before
+ *             they must be sliced to reduce the amount of waste. A
+ *             negative can be passed to disable slicing.
+ * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    format similar to the format of the source data will be used. The
+ *    default blending equations of Cogl expect premultiplied color data;
+ *    the main use of passing a non-premultiplied format here is if you
+ *    have non-premultiplied source data and are going to adjust the blend
+ *    mode (see cogl_material_set_blend()) or use the data for something
+ *    other than straight blending.
+ * @error: A #CoglError to catch exceptional errors or %NULL
+ *
+ * Creates a new #CoglTexture2DSliced texture based on data residing
+ * in a bitmap.
+ *
+ * A #CoglTexture2DSliced may internally be comprised of 1 or more
+ * #CoglTexture2D textures depending on GPU limitations.  For example
+ * if the GPU only supports power-of-two sized textures then a sliced
+ * texture will turn a non-power-of-two size into a combination of
+ * smaller power-of-two sized textures. If the requested texture size
+ * is larger than is supported by the hardware then the texture will
+ * be sliced into smaller textures that can be accessed by the
+ * hardware.
+ *
+ * @max_waste is used as a threshold for recursively slicing the
+ * right-most or bottom-most slices into smaller sizes until the
+ * wasted padding at the bottom and right of the textures is less than
+ * specified. A negative @max_waste will disable slicing.
+ *
+ * <note>It's possible for the allocation of a sliced texture to fail
+ * later due to impossible slicing constraints if a negative
+ * @max_waste value is given. If the given virtual texture size is
+ * larger than is supported by the hardware but slicing is disabled
+ * the texture size would be too large to handle.</note>
+ *
+ * Return value: A newly created #CoglTexture2DSliced or %NULL on
+ *               failure and @error will be updated.
+ *
+ * Since: 1.16
+ */
+CoglTexture2DSliced *
+cogl_texture_2d_sliced_new_from_bitmap (CoglBitmap *bmp,
+                                        int max_waste,
+                                        CoglPixelFormat internal_format,
+                                        CoglError **error);
+
+/**
  * cogl_is_texture_2d_sliced:
  * @object: A #CoglObject pointer
  *