Sample Code III- Texture copy/upload/download

An instance of GLBuffer represents an OpenGL resource, or it contains a pointer to system memory. In either case, one thing is certain: if you want "a copy of a GLBuffer instance", you cannot simply make another copy of the struct- bad things will happen as the underlying image data either won't be duplicated.

It is strongly recommended that you use GLBufferRef instead of GLBuffer if you just want to share a given GLBuffer instance with another object (displaying the same texture in two different views, for example). As long as you use GLBufferRef and ensure that you set any GLBufferRefs you maintain to nullptr as soon as you no longer use them, all the underlying GPU/CPU resources will be freed/pooled and you'll have plenty of VRAM available. Remember, GLBuffers come from and are returned to pools: obtaining a new buffer and setting a buffer to nil are typically very fast and very cheap (within reason).

//  allocate an RGBA OpenGL texture
GLBufferRef         origTex = CreateRGBATex(VVGL::Size(1920,1080));
//  print the name and source rect of the RGBA texture
cout << "origTex is " << orgTex->name << ", srcRect is " << origTex->srcRect << endl;

//  make another var- both vars refer to the same underlying GLBuffer instance
GLBufferRef         sameGLBufferNewVar = origTex;
//  modify the srcRect of the new texture var
sameGLBufferNewVar->srcRect = VVGL::Rect(10,10,1900,1060);

//  print the name and source rect of the new var
cout << "sameGLBufferNewVar is " << sameGLBufferNewVar->name;
cout << ", srcRect is " << sameGLBufferNewVar->srcRect << endl;

//  print the source rect of the original- observe that it has changed!
cout << "origTex srcRect is now " << origTex->srcRect << endl;

GLBufferRef is great, but if you're working with it and you modify a property- like 'srcRect', for example- then every other GLBufferRef for that same GLBuffer will immediately inherit that change. This is not always desirable- for example, you may want to crop a GLBufferRef for use in one particular scene, or use a larger texture-based GLBuffer as the source of many smaller texture-based GLBuffers that all share the same GL resource (texture atlas). The function GLBufferCopy() accepts a GLBufferRef, makes a new GLBuffer instance that has a strong reference to the GLBuffer instance you passed in, and returns a GLBufferRef for the new instance. Because it's an entirely different GLBuffer, you can modify the superficial properties without affecting the original GLBuffer or any of its refs- but because it's the same underlying GL resource, nothing was actually copied and the resource will automatically be retained as long as necessary. Copying buffers in this manner is quick and cheap because the actual image data isn't being duplicated.

//  allocate an RGBA OpenGL texture
GLBufferRef         origTex = CreateRGBATex(VVGL::Size(1920,1080));
//  print the name and source rect of the RGBA texture
cout << "origTex is " << orgTex->name << ", srcRect is " << origTex->srcRect << endl;

//  make a copy of the GLBufferRef- this makes another 
//  instance of GLBuffer that retains the passed GLBuffer.
GLBufferRef         sameTexNewBufferNewVar = GLBufferCopy(origTex);
//  modify the srcRect of the new texture var
sameTexNewBufferNewVar->srcRect = VVGL::Rect(10,10,1900,1060);

//  print the name and source rect of the new var
cout << "sameTexNewBufferNewVar is " << sameTexNewBufferNewVar->name;
cout << ", srcRect is " << sameTexNewBufferNewVar->srcRect << endl;

//  print the source rect of the original- observe that it has changed!
cout << "origTex srcRect is " << origTex->srcRect << endl;  

Sometimes you actually want to copy the contents of a GLBuffer to another GLBuffer. For this, VVGL offers a couple different classes that specialize in the more commonly encountered types of copies so far:

• GLTexToTexCopier copies texture-type GLBuffers to other texture-type GLBuffers. Texture-to-texture copies are relatively fast, and resizing them is relatively easy.

  //  Same creation semantics as GLScene: if you don't explicitly provide an OpenGL 
  //  context, it will create its own context in the global buffer pool's sharegroup.
  GLTexToTexCopierRef     texToTexCopier = CreateGLTexToTexCopierRef();
  
  //  make a source texture, then copy it into a new texture
  GLBufferRef         tmpSrcTex = CreateRGBATex(VVGL::Size(1920,1080));
  GLBufferRef         tmpDstTex = texToTexCopier->copyToNewBuffer(tmpSrcTex);

• GLTexToCPUCopier copies texture-type GLBuffers to CPU-type GLBuffers. It has two basic access points, one which is suitable for performing immediate one-shot texture downloads, and another asynchronous mode which has been optimized to be substantially more efficient.

  //  Same creation semantics as GLScene: if you don't explicitly provide an OpenGL 
  //  context, it will create its own context in the global buffer pool's sharegroup.
  GLTexToCPUCopierRef     texToCPUCopier = CreateGLTexToCPUCopierRef();
  
  //  make a source texture- we're going to download this
  GLBufferRef         tmpTexBuffer = CreateRGBATex(VVGL::Size(1920,1080));
  
  //  download the source texture to system memory immediately- good for quick one-shot downloads
  GLBufferRef         tmpBuffer = texToCPUCopier->downloadTexToCPU(tmpTexBuffer);
  //  because we didn't provide a CPU-type buffer, 'tmpBuffer' is a PBO-type buffer
  //  that has been mapped into system memory, and can be accessed like this:
  if (tmpBuffer!=nullptr && tmpBuffer->pboMapped) {
      void                *tmpBufferData = tmpBuffer->cpuBackingPtr;
      uint32_t            bytesPerRow = tmpBuffer->calculateBackingBytesPerRow();
      uint32_t            totalLength = tmpBuffer->calculateBackingLength();
  }
  
  //  if you're receiving a stream of textures to download, there's a more efficient way:
  GLBufferRef         newFrameTexture = XXX;  //  provided by something else in the real world
  //  GLTexToCPUCopier uses a PBO to do async/n-buffered downloads, so the 
  //  first frame or two won't get returned until you call it again later.
  GLBufferRef         downloadedFrame = texToCPUCopier->streamTexToCPU(newFrameTexture);
  if (downloadedFrame != nullptr) {
      void        *downloadedData = NULL;
      uint32_t    bytesPerRow = 0;
      uint32_t    totalLength = 0;
      if ((downloadedFrame->desc.type == Type_PBO && downloadedFrame->pboMapped)  ||
      (downloadedFrame->desc.type == Type_CPU))
      {
          downloadedData = downloadedFrame->cpuBackingPtr;
          bytesPerRow = downloadedFrame->calculateBackingBytesPerRow();
          totalLength = downloadedFrame->calculateBackingLength();
      }
      //  ..now do something with the downloaded data- encode to video, export to image, etc.
  }

• GLCPUToTexCopier copies CPU-type GLBuffers to texture-type GLBuffers. It also has two basic access modes, one which is optimized for immediate upload and another, more efficient/optimized mode for streaming data to textures.

  //  Same creation semantics as GLScene: if you don't explicitly provide an OpenGL 
  //  context, it will create its own context in the global buffer pool's sharegroup.
  GLCPUToTexCopierRef     cpuToTexCopier = CreateGLCPUToTexCopierRef();
  
  GLBufferRef         tmpCPUTypeBuffer = XXX; //  non-null in the real world
  
  //  upload the cpu buffer to a GL texture immediately- good for quick one-shot uploads
  GLBufferRef         tmpBuffer = cpuToTexCopier->uploadCPUToTex(tmpCPUTypeBuffer);
  
  //  if you're receiving a stream of images to upload, there's a more efficient pipeline:
  GLBufferRef         newFrameCPUBuffer = XXX;    //  non-null in the real world
  //  GLCPUToTexCopier uses a PBO to do async/n-buffered uploads, so the
  //  first frame or two won't get returned until you call it again later.
  GLBufferRef         uploadedFrame = cpuToTexCopier->streamCPUToTex(newFrameCPUBuffer);
  if (uploadedFrame != nullptr)   {
      //  do something with the uploaded texture
  }