modules/core/doc/opengl_interop.rst

   1 OpenGL interoperability
   2 =======================
   3
   4 .. highlight:: cpp
   5
   6
   7
   8 General Information
   9 -------------------
  10 This section describes OpenGL interoperability.
  11
  12 To enable OpenGL support, configure OpenCV using ``CMake`` with ``WITH_OPENGL=ON`` .
  13 Currently OpenGL is supported only with WIN32, GTK and Qt backends on Windows and Linux (MacOS and Android are not supported).
  14 For GTK backend ``gtkglext-1.0`` library is required.
  15
  16 To use OpenGL functionality you should first create OpenGL context (window or frame buffer).
  17 You can do this with :ocv:func:`namedWindow` function or with other OpenGL toolkit (GLUT, for example).
  18
  19
  20
  21 ogl::Buffer
  22 -----------
  23 Smart pointer for OpenGL buffer object with reference counting.
  24
  25 .. ocv:class:: ogl::Buffer
  26
  27 Buffer Objects are OpenGL objects that store an array of unformatted memory allocated by the OpenGL context.
  28 These can be used to store vertex data, pixel data retrieved from images or the framebuffer, and a variety of other things.
  29
  30 ``ogl::Buffer`` has interface similar with :ocv:class:`Mat` interface and represents 2D array memory.
  31
  32 ``ogl::Buffer`` supports memory transfers between host and device and also can be mapped to CUDA memory.
  33
  34
  35
  36 ogl::Buffer::Target
  37 -------------------
  38 The target defines how you intend to use the buffer object.
  39
  40 .. ocv:enum:: ogl::Buffer::Target
  41
  42     .. ocv:emember:: ARRAY_BUFFER
  43
  44         The buffer will be used as a source for vertex data.
  45
  46     .. ocv:emember:: ELEMENT_ARRAY_BUFFER
  47
  48         The buffer will be used for indices (in ``glDrawElements`` or :ocv:func:`ogl::render`, for example).
  49
  50     .. ocv:emember:: PIXEL_PACK_BUFFER
  51
  52         The buffer will be used for reading from OpenGL textures.
  53
  54     .. ocv:emember:: PIXEL_UNPACK_BUFFER
  55
  56         The buffer will be used for writing to OpenGL textures.
  57
  58
  59
  60 ogl::Buffer::Buffer
  61 -------------------
  62 The constructors.
  63
  64 .. ocv:function:: ogl::Buffer::Buffer()
  65
  66 .. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, unsigned int abufId, bool autoRelease = false)
  67
  68 .. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, unsigned int abufId, bool autoRelease = false)
  69
  70 .. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
  71
  72 .. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
  73
  74 .. ocv:function:: ogl::Buffer::Buffer(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
  75
  76     :param arows: Number of rows in a 2D array.
  77
  78     :param acols: Number of columns in a 2D array.
  79
  80     :param asize: 2D array size.
  81
  82     :param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
  83
  84     :param abufId: Buffer object name.
  85
  86     :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` or ``std::vector`` ).
  87
  88     :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
  89
  90     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
  91
  92 Creates empty ``ogl::Buffer`` object, creates ``ogl::Buffer`` object from existed buffer ( ``abufId`` parameter),
  93 allocates memory for ``ogl::Buffer`` object or copies from host/device memory.
  94
  95
  96
  97 ogl::Buffer::create
  98 -------------------
  99 Allocates memory for ``ogl::Buffer`` object.
 100
 101 .. ocv:function:: void ogl::Buffer::create(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
 102
 103 .. ocv:function:: void ogl::Buffer::create(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
 104
 105     :param arows: Number of rows in a 2D array.
 106
 107     :param acols: Number of columns in a 2D array.
 108
 109     :param asize: 2D array size.
 110
 111     :param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
 112
 113     :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
 114
 115     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
 116
 117
 118
 119 ogl::Buffer::release
 120 --------------------
 121 Decrements the reference counter and destroys the buffer object if needed.
 122
 123 .. ocv:function:: void ogl::Buffer::release()
 124
 125
 126
 127 ogl::Buffer::setAutoRelease
 128 ---------------------------
 129 Sets auto release mode.
 130
 131 .. ocv:function:: void ogl::Buffer::setAutoRelease(bool flag)
 132
 133     :param flag: Auto release mode (if true, release will be called in object's destructor).
 134
 135 The lifetime of the OpenGL object is tied to the lifetime of the context.
 136 If OpenGL context was bound to a window it could be released at any time (user can close a window).
 137 If object's destructor is called after destruction of the context it will cause an error.
 138 Thus ``ogl::Buffer`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
 139 This function can force ``ogl::Buffer`` destructor to destroy OpenGL object.
 140
 141
 142
 143 ogl::Buffer::copyFrom
 144 ---------------------
 145 Copies from host/device memory to OpenGL buffer.
 146
 147 .. ocv:function:: void ogl::Buffer::copyFrom(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
 148
 149     :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` or ``std::vector`` ).
 150
 151     :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
 152
 153     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
 154
 155
 156
 157 ogl::Buffer::copyTo
 158 -------------------
 159 Copies from OpenGL buffer to host/device memory or another OpenGL buffer object.
 160
 161 .. ocv:function:: void ogl::Buffer::copyTo(OutputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false) const
 162
 163     :param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` , ``std::vector`` or ``ogl::Buffer`` ).
 164
 165     :param target: Buffer usage for destination buffer (if ``arr`` is OpenGL buffer).
 166
 167     :param autoRelease: Auto release mode for destination buffer (if ``arr`` is OpenGL buffer).
 168
 169
 170
 171 ogl::Buffer::clone
 172 ------------------
 173 Creates a full copy of the buffer object and the underlying data.
 174
 175 .. ocv:function:: Buffer ogl::Buffer::clone(Target target = ARRAY_BUFFER, bool autoRelease = false) const
 176
 177     :param target: Buffer usage for destination buffer.
 178
 179     :param autoRelease: Auto release mode for destination buffer.
 180
 181
 182
 183 ogl::Buffer::bind
 184 -----------------
 185 Binds OpenGL buffer to the specified buffer binding point.
 186
 187 .. ocv:function:: void ogl::Buffer::bind(Target target) const
 188
 189     :param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
 190
 191
 192
 193 ogl::Buffer::unbind
 194 -------------------
 195 Unbind any buffers from the specified binding point.
 196
 197 .. ocv:function:: static void ogl::Buffer::unbind(Target target)
 198
 199     :param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
 200
 201
 202
 203 ogl::Buffer::mapHost
 204 --------------------
 205 Maps OpenGL buffer to host memory.
 206
 207 .. ocv:function:: Mat ogl::Buffer::mapHost(Access access)
 208
 209     :param access: Access policy, indicating whether it will be possible to read from, write to, or both read from and write to the buffer object's mapped data store. The symbolic constant must be ``ogl::Buffer::READ_ONLY`` , ``ogl::Buffer::WRITE_ONLY`` or ``ogl::Buffer::READ_WRITE`` .
 210
 211 ``mapHost`` maps to the client's address space the entire data store of the buffer object.
 212 The data can then be directly read and/or written relative to the returned pointer, depending on the specified ``access`` policy.
 213
 214 A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapHost` before its buffer object is used.
 215
 216 This operation can lead to memory transfers between host and device.
 217
 218 Only one buffer object can be mapped at a time.
 219
 220
 221
 222 ogl::Buffer::unmapHost
 223 ----------------------
 224 Unmaps OpenGL buffer.
 225
 226 .. ocv:function:: void ogl::Buffer::unmapHost()
 227
 228
 229
 230 ogl::Buffer::mapDevice
 231 ----------------------
 232 Maps OpenGL buffer to CUDA device memory.
 233
 234 .. ocv:function:: gpu::GpuMat ogl::Buffer::mapDevice()
 235
 236 This operatation doesn't copy data.
 237 Several buffer objects can be mapped to CUDA memory at a time.
 238
 239 A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapDevice` before its buffer object is used.
 240
 241
 242
 243 ogl::Buffer::unmapDevice
 244 ------------------------
 245 Unmaps OpenGL buffer.
 246
 247 .. ocv:function:: void ogl::Buffer::unmapDevice()
 248
 249
 250
 251 ogl::Texture2D
 252 --------------
 253 Smart pointer for OpenGL 2D texture memory with reference counting.
 254
 255 .. ocv:class:: ogl::Texture2D
 256
 257
 258
 259 ogl::Texture2D::Format
 260 ----------------------
 261 An Image Format describes the way that the images in Textures store their data.
 262
 263 .. ocv:enum:: ogl::Texture2D::Format
 264
 265     .. ocv:emember:: NONE
 266     .. ocv:emember:: DEPTH_COMPONENT
 267     .. ocv:emember:: RGB
 268     .. ocv:emember:: RGBA
 269
 270
 271
 272 ogl::Texture2D::Texture2D
 273 -------------------------
 274 The constructors.
 275
 276 .. ocv:function:: ogl::Texture2D::Texture2D()
 277
 278 .. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, unsigned int atexId, bool autoRelease = false)
 279
 280 .. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, unsigned int atexId, bool autoRelease = false)
 281
 282 .. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, bool autoRelease = false)
 283
 284 .. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, bool autoRelease = false)
 285
 286 .. ocv:function:: ogl::Texture2D::Texture2D(InputArray arr, bool autoRelease = false)
 287
 288     :param arows: Number of rows.
 289
 290     :param acols: Number of columns.
 291
 292     :param asize: 2D array size.
 293
 294     :param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
 295
 296     :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` or :ocv:class:`ogl::Buffer` ).
 297
 298     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
 299
 300 Creates empty ``ogl::Texture2D`` object, allocates memory for ``ogl::Texture2D`` object or copies from host/device memory.
 301
 302
 303
 304 ogl::Texture2D::create
 305 ----------------------
 306 Allocates memory for ``ogl::Texture2D`` object.
 307
 308 .. ocv:function:: void ogl::Texture2D::create(int arows, int acols, Format aformat, bool autoRelease = false)
 309
 310 .. ocv:function:: void ogl::Texture2D::create(Size asize, Format aformat, bool autoRelease = false)
 311
 312     :param arows: Number of rows.
 313
 314     :param acols: Number of columns.
 315
 316     :param asize: 2D array size.
 317
 318     :param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
 319
 320     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
 321
 322
 323
 324 ogl::Texture2D::release
 325 -----------------------
 326 Decrements the reference counter and destroys the texture object if needed.
 327
 328 .. ocv:function:: void ogl::Texture2D::release()
 329
 330
 331
 332 ogl::Texture2D::setAutoRelease
 333 ------------------------------
 334 Sets auto release mode.
 335
 336 .. ocv:function:: void ogl::Texture2D::setAutoRelease(bool flag)
 337
 338     :param flag: Auto release mode (if true, release will be called in object's destructor).
 339
 340 The lifetime of the OpenGL object is tied to the lifetime of the context.
 341 If OpenGL context was bound to a window it could be released at any time (user can close a window).
 342 If object's destructor is called after destruction of the context it will cause an error.
 343 Thus ``ogl::Texture2D`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
 344 This function can force ``ogl::Texture2D`` destructor to destroy OpenGL object.
 345
 346
 347
 348 ogl::Texture2D::copyFrom
 349 ------------------------
 350 Copies from host/device memory to OpenGL texture.
 351
 352 .. ocv:function:: void ogl::Texture2D::copyFrom(InputArray arr, bool autoRelease = false)
 353
 354     :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` or :ocv:class:`ogl::Buffer` ).
 355
 356     :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
 357
 358
 359
 360 ogl::Texture2D::copyTo
 361 ----------------------
 362 Copies from OpenGL texture to host/device memory or another OpenGL texture object.
 363
 364 .. ocv:function:: void ogl::Texture2D::copyTo(OutputArray arr, int ddepth = CV_32F, bool autoRelease = false) const
 365
 366     :param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`gpu::GpuMat` , :ocv:class:`ogl::Buffer` or ``ogl::Texture2D`` ).
 367
 368     :param ddepth: Destination depth.
 369
 370     :param autoRelease: Auto release mode for destination buffer (if ``arr`` is OpenGL buffer or texture).
 371
 372
 373
 374 ogl::Texture2D::bind
 375 --------------------
 376 Binds texture to current active texture unit for ``GL_TEXTURE_2D`` target.
 377
 378 .. ocv:function:: void ogl::Texture2D::bind() const
 379
 380
 381
 382 ogl::Arrays
 383 -----------
 384 Wrapper for OpenGL Client-Side Vertex arrays.
 385
 386 .. ocv:class:: ogl::Arrays
 387
 388 ``ogl::Arrays`` stores vertex data in :ocv:class:`ogl::Buffer` objects.
 389
 390
 391
 392 ogl::Arrays::setVertexArray
 393 ---------------------------
 394 Sets an array of vertex coordinates.
 395
 396 .. ocv:function:: void ogl::Arrays::setVertexArray(InputArray vertex)
 397
 398     :param vertex: array with vertex coordinates, can be both host and device memory.
 399
 400
 401
 402 ogl::Arrays::resetVertexArray
 403 -----------------------------
 404 Resets vertex coordinates.
 405
 406 .. ocv:function:: void ogl::Arrays::resetVertexArray()
 407
 408
 409
 410 ogl::Arrays::setColorArray
 411 --------------------------
 412 Sets an array of vertex colors.
 413
 414 .. ocv:function:: void ogl::Arrays::setColorArray(InputArray color)
 415
 416     :param color: array with vertex colors, can be both host and device memory.
 417
 418
 419
 420 ogl::Arrays::resetColorArray
 421 ----------------------------
 422 Resets vertex colors.
 423
 424 .. ocv:function:: void ogl::Arrays::resetColorArray()
 425
 426
 427
 428 ogl::Arrays::setNormalArray
 429 ---------------------------
 430 Sets an array of vertex normals.
 431
 432 .. ocv:function:: void ogl::Arrays::setNormalArray(InputArray normal)
 433
 434     :param normal: array with vertex normals, can be both host and device memory.
 435
 436
 437
 438 ogl::Arrays::resetNormalArray
 439 -----------------------------
 440 Resets vertex normals.
 441
 442 .. ocv:function:: void ogl::Arrays::resetNormalArray()
 443
 444
 445
 446 ogl::Arrays::setTexCoordArray
 447 -----------------------------
 448 Sets an array of vertex texture coordinates.
 449
 450 .. ocv:function:: void ogl::Arrays::setTexCoordArray(InputArray texCoord)
 451
 452     :param texCoord: array with vertex texture coordinates, can be both host and device memory.
 453
 454
 455
 456 ogl::Arrays::resetTexCoordArray
 457 -------------------------------
 458 Resets vertex texture coordinates.
 459
 460 .. ocv:function:: void ogl::Arrays::resetTexCoordArray()
 461
 462
 463
 464 ogl::Arrays::release
 465 --------------------
 466 Releases all inner buffers.
 467
 468 .. ocv:function:: void ogl::Arrays::release()
 469
 470
 471
 472 ogl::Arrays::setAutoRelease
 473 ---------------------------
 474 Sets auto release mode all inner buffers.
 475
 476 .. ocv:function:: void ogl::Arrays::setAutoRelease(bool flag)
 477
 478     :param flag: Auto release mode.
 479
 480
 481
 482 ogl::Arrays::bind
 483 -----------------
 484 Binds all vertex arrays.
 485
 486 .. ocv:function:: void ogl::Arrays::bind() const
 487
 488
 489
 490 ogl::Arrays::size
 491 -----------------
 492 Returns the vertex count.
 493
 494 .. ocv:function:: int ogl::Arrays::size() const
 495
 496
 497
 498 ogl::render
 499 -----------
 500 Render OpenGL texture or primitives.
 501
 502 .. ocv:function:: void ogl::render(const Texture2D& tex, Rect_<double> wndRect = Rect_<double>(0.0, 0.0, 1.0, 1.0), Rect_<double> texRect = Rect_<double>(0.0, 0.0, 1.0, 1.0))
 503
 504 .. ocv:function:: void ogl::render(const Arrays& arr, int mode = POINTS, Scalar color = Scalar::all(255))
 505
 506 .. ocv:function:: void ogl::render(const Arrays& arr, InputArray indices, int mode = POINTS, Scalar color = Scalar::all(255))
 507
 508     :param tex: Texture to draw.
 509
 510     :param wndRect: Region of window, where to draw a texture (normalized coordinates).
 511
 512     :param texRect: Region of texture to draw (normalized coordinates).
 513
 514     :param arr: Array of privitives vertices.
 515
 516     :param indices: Array of vertices indices (host or device memory).
 517
 518     :param mode: Render mode. Available options:
 519
 520         * **POINTS**
 521         * **LINES**
 522         * **LINE_LOOP**
 523         * **LINE_STRIP**
 524         * **TRIANGLES**
 525         * **TRIANGLE_STRIP**
 526         * **TRIANGLE_FAN**
 527         * **QUADS**
 528         * **QUAD_STRIP**
 529         * **POLYGON**
 530
 531     :param color: Color for all vertices. Will be used if ``arr`` doesn't contain color array.
 532
 533
 534
 535 gpu::setGlDevice
 536 ----------------
 537 Sets a CUDA device and initializes it for the current thread with OpenGL interoperability.
 538
 539 .. ocv:function:: void gpu::setGlDevice( int device = 0 )
 540
 541     :param device: System index of a GPU device starting with 0.
 542
 543 This function should be explicitly called after OpenGL context creation and before any CUDA calls.