cogl/cogl-buffer.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C)2010 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  *
  22  *
  23  * Authors:
  24  *   Damien Lespiau <damien.lespiau@intel.com>
  25  *   Robert Bragg <robert@linux.intel.com>
  26  */
  27
  28 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  29 #error "Only <cogl/cogl.h> can be included directly."
  30 #endif
  31
  32 #ifndef __COGL_BUFFER_H__
  33 #define __COGL_BUFFER_H__
  34
  35 #include <glib.h>
  36 #include <cogl/cogl-types.h>
  37
  38 G_BEGIN_DECLS
  39
  40 /**
  41  * SECTION:cogl-buffer
  42  * @short_description: Common buffer functions, including data upload APIs
  43  * @stability: unstable
  44  *
  45  * The CoglBuffer API provides a common interface to manipulate
  46  * buffers that have been allocated either via cogl_pixel_buffer_new()
  47  * or cogl_attribute_buffer_new(). The API allows you to upload data
  48  * to these buffers and define usage hints that help Cogl manage your
  49  * buffer optimally.
  50  *
  51  * Data can either be uploaded by supplying a pointer and size so Cogl
  52  * can copy your data, or you can mmap() a CoglBuffer and then you can
  53  * copy data to the buffer directly.
  54  *
  55  * One of the most common uses for CoglBuffers is to upload texture
  56  * data asynchronously since the ability to mmap the buffers into
  57  * the CPU makes it possible for another thread to handle the IO
  58  * of loading an image file and unpacking it into the mapped buffer
  59  * without blocking other Cogl operations.
  60  */
  61
  62 #define COGL_BUFFER(buffer)     ((CoglBuffer *)(buffer))
  63
  64 typedef struct _CoglBuffer CoglBuffer;
  65
  66 /**
  67  * cogl_is_buffer:
  68  * @object: a buffer object
  69  *
  70  * Checks whether @buffer is a buffer object.
  71  *
  72  * Return value: %TRUE if the handle is a CoglBuffer, and %FALSE otherwise
  73  *
  74  * Since: 1.2
  75  * Stability: unstable
  76  */
  77 gboolean
  78 cogl_is_buffer (void *object);
  79
  80 /**
  81  * cogl_buffer_get_size:
  82  * @buffer: a buffer object
  83  *
  84  * Retrieves the size of buffer
  85  *
  86  * Return value: the size of the buffer in bytes
  87  *
  88  * Since: 1.2
  89  * Stability: unstable
  90  */
  91 unsigned int
  92 cogl_buffer_get_size (CoglBuffer *buffer);
  93
  94 /**
  95  * CoglBufferUpdateHint:
  96  * @COGL_BUFFER_UPDATE_HINT_STATIC: the buffer will not change over time
  97  * @COGL_BUFFER_UPDATE_HINT_DYNAMIC: the buffer will change from time to time
  98  * @COGL_BUFFER_UPDATE_HINT_STREAM: the buffer will be used once or a couple of
  99  *   times
 100  *
 101  * The update hint on a buffer allows the user to give some detail on how often
 102  * the buffer data is going to be updated.
 103  *
 104  * Since: 1.2
 105  * Stability: unstable
 106  */
 107 typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/
 108   COGL_BUFFER_UPDATE_HINT_STATIC,
 109   COGL_BUFFER_UPDATE_HINT_DYNAMIC,
 110   COGL_BUFFER_UPDATE_HINT_STREAM
 111 } CoglBufferUpdateHint;
 112
 113 /**
 114  * cogl_buffer_set_update_hint:
 115  * @buffer: a buffer object
 116  * @hint: the new hint
 117  *
 118  * Sets the update hint on a buffer. See #CoglBufferUpdateHint for a description
 119  * of the available hints.
 120  *
 121  * Since: 1.2
 122  * Stability: unstable
 123  */
 124 void
 125 cogl_buffer_set_update_hint (CoglBuffer          *buffer,
 126                              CoglBufferUpdateHint hint);
 127
 128 /**
 129  * cogl_buffer_get_update_hint:
 130  * @buffer: a buffer object
 131  *
 132  * Retrieves the update hints set using cogl_buffer_set_update_hint()
 133  *
 134  * Return value: the #CoglBufferUpdateHint currently used by the buffer
 135  *
 136  * Since: 1.2
 137  * Stability: unstable
 138  */
 139 CoglBufferUpdateHint
 140 cogl_buffer_get_update_hint (CoglBuffer *buffer);
 141
 142 /**
 143  * CoglBufferAccess:
 144  * @COGL_BUFFER_ACCESS_READ: the buffer will be read
 145  * @COGL_BUFFER_ACCESS_WRITE: the buffer will written to
 146  * @COGL_BUFFER_ACCESS_READ_WRITE: the buffer will be used for both reading and
 147  *   writing
 148  *
 149  * The access hints for cogl_buffer_set_update_hint()
 150  *
 151  * Since: 1.2
 152  * Stability: unstable
 153  */
 154 typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/
 155  COGL_BUFFER_ACCESS_READ       = 1 << 0,
 156  COGL_BUFFER_ACCESS_WRITE      = 1 << 1,
 157  COGL_BUFFER_ACCESS_READ_WRITE = COGL_BUFFER_ACCESS_READ | COGL_BUFFER_ACCESS_WRITE
 158 } CoglBufferAccess;
 159
 160
 161 /**
 162  * CoglBufferMapHint:
 163  * @COGL_BUFFER_MAP_HINT_DISCARD: Tells Cogl that you plan to replace
 164  *    all the buffer's contents.
 165  *
 166  * Hints to Cogl about how you are planning to modify the data once it
 167  * is mapped.
 168  *
 169  * Since: 1.4
 170  * Stability: unstable
 171  */
 172 typedef enum { /*< prefix=COGL_BUFFER_MAP_HINT >*/
 173   COGL_BUFFER_MAP_HINT_DISCARD = 1 << 0
 174 } CoglBufferMapHint;
 175
 176 /**
 177  * cogl_buffer_map:
 178  * @buffer: a buffer object
 179  * @access: how the mapped buffer will be used by the application
 180  * @hints: A mask of #CoglBufferMapHint<!-- -->s that tell Cogl how
 181  *   the data will be modified once mapped.
 182  *
 183  * Maps the buffer into the application address space for direct access.
 184  *
 185  * It is strongly recommended that you pass
 186  * %COGL_BUFFER_MAP_HINT_DISCARD as a hint if you are going to replace
 187  * all the buffer's data. This way if the buffer is currently being
 188  * used by the GPU then the driver won't have to stall the CPU and
 189  * wait for the hardware to finish because it can instead allocate a
 190  * new buffer to map.
 191  *
 192  * The behaviour is undefined if you access the buffer in a way
 193  * conflicting with the @access mask you pass. It is also an error to
 194  * release your last reference while the buffer is mapped.
 195  *
 196  * Return value: A pointer to the mapped memory or %NULL is the call fails
 197  *
 198  * Since: 1.2
 199  * Stability: unstable
 200  */
 201 void *
 202 cogl_buffer_map (CoglBuffer        *buffer,
 203                  CoglBufferAccess   access,
 204                  CoglBufferMapHint  hints);
 205
 206 /**
 207  * cogl_buffer_unmap:
 208  * @buffer: a buffer object
 209  *
 210  * Unmaps a buffer previously mapped by cogl_buffer_map().
 211  *
 212  * Since: 1.2
 213  * Stability: unstable
 214  */
 215 void
 216 cogl_buffer_unmap (CoglBuffer *buffer);
 217
 218 /**
 219  * cogl_buffer_set_data:
 220  * @buffer: a buffer object
 221  * @offset: destination offset (in bytes) in the buffer
 222  * @data: a pointer to the data to be copied into the buffer
 223  * @size: number of bytes to copy
 224  *
 225  * Updates part of the buffer with new data from @data. Where to put this new
 226  * data is controlled by @offset and @offset + @data should be less than the
 227  * buffer size.
 228  *
 229  * Return value: %TRUE is the operation succeeded, %FALSE otherwise
 230  *
 231  * Since: 1.2
 232  * Stability: unstable
 233  */
 234 gboolean
 235 cogl_buffer_set_data (CoglBuffer  *buffer,
 236                       gsize        offset,
 237                       const void  *data,
 238                       gsize        size);
 239
 240 G_END_DECLS
 241
 242 #endif /* __COGL_BUFFER_H__ */