Added ability to select cubemap face for framebuffer attachments. PR#679.

include/bgfx/bgfx.h

@@ -1362,8 +1362,8 @@ namespace bgfx
 	/// Update Cube texture.
 	///
 	/// @param[in] _handle Texture handle.
-	/// @param[in] _side Cubemap side, where 0 is +X, 1 is -X, 2 is +Y, 3 is
-	///   -Y, 4 is +Z, and 5 is -Z.
+	/// @param[in] _side Cubemap side `BGFX_CUBE_MAP_<POSITIVE or NEGATIVE>_<AXIS>`,
+	///   where 0 is +X, 1 is -X, 2 is +Y, 3 is -Y, 4 is +Z, and 5 is -Z.
 	///
 	///                  +----------+
 	///                  |-z       2|
@@ -1470,6 +1470,19 @@ namespace bgfx
 	///
 	FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, bool _destroyTextures = false);
 
+	/// Create frame buffer.
+	///
+	/// @param[in] _num Number of texture attachments.
+	/// @param[in] _handles Texture attachments.
+	/// @param[in] _side Side for cubemap texture attachements.
+	///   See: `BGFX_CUBE_MAP_<POSITIVE or NEGATIVE>_<AXIS>`.
+	/// @param[in] _destroyTextures If true, textures will be destroyed when
+	///   frame buffer is destroyed.
+	///
+	/// @attention C99 equivalent is `bgfx_create_frame_buffer_from_handles`.
+	///
+	FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side, bool _destroyTextures = false);
+
 	/// Create frame buffer for multiple window rendering.
 	///
 	/// @param[in] _nwh OS' target native window handle.

include/bgfx/bgfxdefines.h

@@ -6,7 +6,7 @@
 #ifndef BGFX_DEFINES_H_HEADER_GUARD
 #define BGFX_DEFINES_H_HEADER_GUARD
 
-#define BGFX_API_VERSION UINT32_C(7)
+#define BGFX_API_VERSION UINT32_C(8)
 
 ///
 #define BGFX_STATE_RGB_WRITE             UINT64_C(0x0000000000000001) //!< Enable RGB write.
@@ -422,4 +422,12 @@
 #define BGFX_HMD_DEVICE_RESOLUTION UINT8_C(0x01) //!< Has HMD native resolution.
 #define BGFX_HMD_RENDERING         UINT8_C(0x02) //!< Rendering to HMD.
 
+///
+#define BGFX_CUBE_MAP_POSITIVE_X UINT8_C(0x00) //!< Cubemap +x.
+#define BGFX_CUBE_MAP_NEGATIVE_X UINT8_C(0x01) //!< Cubemap -x.
+#define BGFX_CUBE_MAP_POSITIVE_Y UINT8_C(0x02) //!< Cubemap +y.
+#define BGFX_CUBE_MAP_NEGATIVE_Y UINT8_C(0x03) //!< Cubemap -y.
+#define BGFX_CUBE_MAP_POSITIVE_Z UINT8_C(0x04) //!< Cubemap +z.
+#define BGFX_CUBE_MAP_NEGATIVE_Z UINT8_C(0x05) //!< Cubemap -z.
+
 #endif // BGFX_DEFINES_H_HEADER_GUARD

include/bgfx/c99/bgfx.h

@@ -639,7 +639,7 @@ BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer(uint16_t _width,
 BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_scaled(bgfx_backbuffer_ratio_t _ratio, bgfx_texture_format_t _format, uint32_t _textureFlags);
 
 /**/
-BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_from_handles(uint8_t _num, const bgfx_texture_handle_t* _handles, bool _destroyTextures);
+BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_from_handles(uint8_t _num, const bgfx_texture_handle_t* _handles, const uint8_t* _side, bool _destroyTextures);
 
 /**/
 BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_from_nwh(void* _nwh, uint16_t _width, uint16_t _height, bgfx_texture_format_t _depthFormat);

include/bgfx/c99/bgfxplatform.h

@@ -137,7 +137,7 @@ typedef struct bgfx_interface_vtbl
     void (*destroy_texture)(bgfx_texture_handle_t _handle);
     bgfx_frame_buffer_handle_t (*create_frame_buffer)(uint16_t _width, uint16_t _height, bgfx_texture_format_t _format, uint32_t _textureFlags);
     bgfx_frame_buffer_handle_t (*create_frame_buffer_scaled)(bgfx_backbuffer_ratio_t _ratio, bgfx_texture_format_t _format, uint32_t _textureFlags);
-    bgfx_frame_buffer_handle_t (*create_frame_buffer_from_handles)(uint8_t _num, const bgfx_texture_handle_t* _handles, bool _destroyTextures);
+    bgfx_frame_buffer_handle_t (*create_frame_buffer_from_handles)(uint8_t _num, const bgfx_texture_handle_t* _handles, const uint8_t* _side, bool _destroyTextures);
     bgfx_frame_buffer_handle_t (*create_frame_buffer_from_nwh)(void* _nwh, uint16_t _width, uint16_t _height, bgfx_texture_format_t _depthFormat);
     void (*destroy_frame_buffer)(bgfx_frame_buffer_handle_t _handle);
     bgfx_uniform_handle_t (*create_uniform)(const char* _name, bgfx_uniform_type_t _type, uint16_t _num);

src/bgfx.cpp

@@ -2260,12 +2260,14 @@ again:
 						_cmdbuf.read(num);
 
 						TextureHandle textureHandles[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
+						uint8_t side[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
 						for (uint32_t ii = 0; ii < num; ++ii)
 						{
 							_cmdbuf.read(textureHandles[ii]);
+							_cmdbuf.read(side[ii]);
 						}
 
-						m_renderCtx->createFrameBuffer(handle, num, textureHandles);
+						m_renderCtx->createFrameBuffer(handle, num, textureHandles, side);
 					}
 				}
 				break;
@@ -3111,6 +3113,12 @@ again:
 	}
 
 	FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, bool _destroyTextures)
+	{
+		uint8_t side[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS] = {};
+		return createFrameBuffer(_num, _handles, side, _destroyTextures);
+	}
+
+	FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side, bool _destroyTextures)
 	{
 		BGFX_CHECK_MAIN_THREAD();
 		BX_CHECK(_num != 0, "Number of frame buffer attachments can't be 0.");
@@ -3119,7 +3127,8 @@ again:
 			, BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS
 			);
 		BX_CHECK(NULL != _handles, "_handles can't be NULL");
-		return s_ctx->createFrameBuffer(_num, _handles, _destroyTextures);
+		BX_CHECK(NULL != _side, "_side can't be NULL");
+		return s_ctx->createFrameBuffer(_num, _handles, _side, _destroyTextures);
 	}
 
 	FrameBufferHandle createFrameBuffer(void* _nwh, uint16_t _width, uint16_t _height, TextureFormat::Enum _depthFormat)
@@ -4114,10 +4123,10 @@ BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_scaled(bgfx_backb
 	return handle.c;
 }
 
-BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_from_handles(uint8_t _num, const bgfx_texture_handle_t* _handles, bool _destroyTextures)
+BGFX_C_API bgfx_frame_buffer_handle_t bgfx_create_frame_buffer_from_handles(uint8_t _num, const bgfx_texture_handle_t* _handles, const uint8_t* _side, bool _destroyTextures)
 {
 	union { bgfx_frame_buffer_handle_t c; bgfx::FrameBufferHandle cpp; } handle;
-	handle.cpp = bgfx::createFrameBuffer(_num, (const bgfx::TextureHandle*)_handles, _destroyTextures);
+	handle.cpp = bgfx::createFrameBuffer(_num, (const bgfx::TextureHandle*)_handles, _side, _destroyTextures);
 	return handle.c;
 }
 

src/bgfx_p.h

@@ -2052,7 +2052,7 @@ namespace bgfx
 		virtual void overrideInternal(TextureHandle _handle, uintptr_t _ptr) = 0;
 		virtual uintptr_t getInternal(TextureHandle _handle) = 0;
 		virtual void destroyTexture(TextureHandle _handle) = 0;
-		virtual void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) = 0;
+		virtual void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) = 0;
 		virtual void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) = 0;
 		virtual void destroyFrameBuffer(FrameBufferHandle _handle) = 0;
 		virtual void createUniform(UniformHandle _handle, UniformType::Enum _type, uint16_t _num, const char* _name) = 0;
@@ -3207,7 +3207,7 @@ namespace bgfx
 				;
 		}
 
-		BGFX_API_FUNC(FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, bool _destroyTextures) )
+		BGFX_API_FUNC(FrameBufferHandle createFrameBuffer(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side, bool _destroyTextures) )
 		{
 			BX_CHECK(checkFrameBuffer(_num, _handles)
 				, "Too many frame buffer attachments (num attachments: %d, max color attachments %d)!"
@@ -3237,6 +3237,7 @@ namespace bgfx
 					BX_UNUSED(bbRatio);
 
 					cmdbuf.write(texHandle);
+					cmdbuf.write(_side[ii]);
 
 					ref.un.m_th[ii] = texHandle;
 					textureIncRef(texHandle);

src/renderer_d3d11.cpp

@@ -1778,9 +1778,9 @@ BX_PRAGMA_DIAGNOSTIC_POP();
 			m_textures[_handle.idx].destroy();
 		}
 
-		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) BX_OVERRIDE
 		{
-			m_frameBuffers[_handle.idx].create(_num, _textureHandles);
+			m_frameBuffers[_handle.idx].create(_num, _textureHandles, _side);
 		}
 
 		void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) BX_OVERRIDE
@@ -4252,7 +4252,7 @@ BX_PRAGMA_DIAGNOSTIC_POP();
 		return handle;
 	}
 
-	void FrameBufferD3D11::create(uint8_t _num, const TextureHandle* _handles)
+	void FrameBufferD3D11::create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side)
 	{
 		for (uint32_t ii = 0; ii < BX_COUNTOF(m_rtv); ++ii)
 		{
@@ -4263,6 +4263,7 @@ BX_PRAGMA_DIAGNOSTIC_POP();
 
 		m_numTh = _num;
 		memcpy(m_th, _handles, _num*sizeof(TextureHandle) );
+		memcpy(m_side, _side, _num);
 
 		postReset();
 	}
@@ -4417,13 +4418,13 @@ BX_PRAGMA_DIAGNOSTIC_POP();
 								{
 									dsvDesc.ViewDimension = D3D11_DSV_DIMENSION_TEXTURE2DMSARRAY;
 									dsvDesc.Texture2DMSArray.ArraySize       = 1;
-									dsvDesc.Texture2DMSArray.FirstArraySlice = 0;
+									dsvDesc.Texture2DMSArray.FirstArraySlice = m_side[ii];
 								}
 								else
 								{
 									dsvDesc.ViewDimension = D3D11_DSV_DIMENSION_TEXTURE2DARRAY;
 									dsvDesc.Texture2DArray.ArraySize       = 1;
-									dsvDesc.Texture2DArray.FirstArraySlice = 0;
+									dsvDesc.Texture2DArray.FirstArraySlice = m_side[ii];
 									dsvDesc.Texture2DArray.MipSlice        = 0;
 								}
 								dsvDesc.Flags = 0;
@@ -4455,7 +4456,7 @@ BX_PRAGMA_DIAGNOSTIC_POP();
 								{
 									desc.ViewDimension = D3D11_RTV_DIMENSION_TEXTURE2DARRAY;
 									desc.Texture2DArray.ArraySize       = 1;
-									desc.Texture2DArray.FirstArraySlice = 0;
+									desc.Texture2DArray.FirstArraySlice = m_side[ii];
 									desc.Texture2DArray.MipSlice        = 0;
 								}
 								DX_CHECK(s_renderD3D11->m_device->CreateRenderTargetView(texture.m_ptr, &desc, &m_rtv[m_num]) );

src/renderer_d3d11.h

@@ -261,7 +261,7 @@ namespace bgfx { namespace d3d11
 		{
 		}
 
-		void create(uint8_t _num, const TextureHandle* _handles);
+		void create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side);
 		void create(uint16_t _denseIdx, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat);
 		uint16_t destroy();
 		void preReset(bool _force = false);
@@ -279,6 +279,7 @@ namespace bgfx { namespace d3d11
 		uint8_t m_num;
 		uint8_t m_numTh;
 		TextureHandle m_th[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
+		uint8_t m_side[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
 	};
 
 	struct TimerQueryD3D11

src/renderer_d3d12.cpp

@@ -1388,9 +1388,9 @@ namespace bgfx { namespace d3d12
 			m_textures[_handle.idx].destroy();
 		}
 
-		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) BX_OVERRIDE
 		{
-			m_frameBuffers[_handle.idx].create(_num, _textureHandles);
+			m_frameBuffers[_handle.idx].create(_num, _textureHandles, _side);
 		}
 
 		void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) BX_OVERRIDE
@@ -4184,10 +4184,11 @@ data.NumQualityLevels = 0;
 		return _state;
 	}
 
-	void FrameBufferD3D12::create(uint8_t _num, const TextureHandle* _handles)
+	void FrameBufferD3D12::create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side)
 	{
 		m_numTh = _num;
 		memcpy(m_th, _handles, _num*sizeof(TextureHandle) );
+		memcpy(m_side, _side, _num);
 
 		postReset();
 	}

src/renderer_d3d12.h

@@ -295,7 +295,7 @@ namespace bgfx { namespace d3d12
 			m_depth.idx = bgfx::invalidHandle;
 		}
 
-		void create(uint8_t _num, const TextureHandle* _handles);
+		void create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side);
 		void create(uint16_t _denseIdx, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat);
 		uint16_t destroy();
 		void preReset();
@@ -312,6 +312,7 @@ namespace bgfx { namespace d3d12
 		uint8_t m_num;
 		uint8_t m_numTh;
 		TextureHandle m_th[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
+		uint8_t m_side[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
 	};
 
 	struct CommandQueueD3D12

src/renderer_d3d9.cpp

@@ -1018,9 +1018,9 @@ namespace bgfx { namespace d3d9
 			m_textures[_handle.idx].destroy();
 		}
 
-		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) BX_OVERRIDE
 		{
-			m_frameBuffers[_handle.idx].create(_num, _textureHandles);
+			m_frameBuffers[_handle.idx].create(_num, _textureHandles, _side);
 		}
 
 		void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) BX_OVERRIDE
@@ -3062,7 +3062,7 @@ namespace bgfx { namespace d3d9
 		}
 	}
 
-	void FrameBufferD3D9::create(uint8_t _num, const TextureHandle* _handles)
+	void FrameBufferD3D9::create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side)
 	{
 		for (uint32_t ii = 0; ii < BX_COUNTOF(m_color); ++ii)
 		{
@@ -3102,7 +3102,7 @@ namespace bgfx { namespace d3d9
 					}
 					else
 					{
-						m_color[m_num] = texture.getSurface();
+						m_color[m_num] = texture.getSurface(_side[ii]);
 					}
 					m_num++;
 				}

src/renderer_d3d9.h

@@ -389,7 +389,7 @@ namespace bgfx { namespace d3d9
 			m_depthHandle.idx = invalidHandle;
 		}
 
-		void create(uint8_t _num, const TextureHandle* _handles);
+		void create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side);
 		void create(uint16_t _denseIdx, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat);
 		uint16_t destroy();
 		HRESULT present();

src/renderer_gl.cpp

@@ -2243,9 +2243,9 @@ namespace bgfx { namespace gl
 			m_textures[_handle.idx].destroy();
 		}
 
-		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) BX_OVERRIDE
 		{
-			m_frameBuffers[_handle.idx].create(_num, _textureHandles);
+			m_frameBuffers[_handle.idx].create(_num, _textureHandles, _side);
 		}
 
 		void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) BX_OVERRIDE
@@ -5017,12 +5017,13 @@ namespace bgfx { namespace gl
 		BX_UNUSED(complete);
 	}
 
-	void FrameBufferGL::create(uint8_t _num, const TextureHandle* _handles)
+	void FrameBufferGL::create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side)
 	{
 		GL_CHECK(glGenFramebuffers(1, &m_fbo[0]) );
 
 		m_numTh = _num;
 		memcpy(m_th, _handles, _num*sizeof(TextureHandle) );
+		memcpy(m_side, _side, _num);
 
 		postReset();
 	}
@@ -5086,7 +5087,7 @@ namespace bgfx { namespace gl
 					else
 					{
 						GLenum target = GL_TEXTURE_CUBE_MAP == texture.m_target
-							? GL_TEXTURE_CUBE_MAP_POSITIVE_X
+							? GL_TEXTURE_CUBE_MAP_POSITIVE_X + m_side[ii]
 							: texture.m_target
 							;
 

src/renderer_gl.h

@@ -1169,7 +1169,7 @@ namespace bgfx { namespace gl
 			memset(m_fbo, 0, sizeof(m_fbo) );
 		}
 
-		void create(uint8_t _num, const TextureHandle* _handles);
+		void create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side);
 		void create(uint16_t _denseIdx, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat);
 		void postReset();
 		uint16_t destroy();
@@ -1184,6 +1184,7 @@ namespace bgfx { namespace gl
 		uint8_t  m_num;
 		uint8_t  m_numTh;
 		TextureHandle m_th[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
+		uint8_t m_side[BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS];
 	};
 
 	struct ProgramGL

src/renderer_mtl.h

@@ -694,7 +694,7 @@ namespace bgfx { namespace mtl
 			m_depthHandle.idx = invalidHandle;
 		}
 
-		void create(uint8_t _num, const TextureHandle* _handles);
+		void create(uint8_t _num, const TextureHandle* _handles, const uint8_t* _side);
 		void create(uint16_t _denseIdx, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat);
 		void postReset();
 		uint16_t destroy();

src/renderer_mtl.mm

@@ -694,9 +694,9 @@ namespace bgfx { namespace mtl
 			m_textures[_handle.idx].destroy();
 		}
 
-		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle _handle, uint8_t _num, const TextureHandle* _textureHandles, const uint8_t* _side) BX_OVERRIDE
 		{
-			m_frameBuffers[_handle.idx].create(_num, _textureHandles);
+			m_frameBuffers[_handle.idx].create(_num, _textureHandles, _side);
 		}
 
 		void createFrameBuffer(FrameBufferHandle _handle, void* _nwh, uint32_t _width, uint32_t _height, TextureFormat::Enum _depthFormat) BX_OVERRIDE
@@ -2079,7 +2079,7 @@ namespace bgfx { namespace mtl
 																	: m_sampler, _stage);
 	}
 
-	void FrameBufferMtl::create(uint8_t _num, const TextureHandle* _handles)
+	void FrameBufferMtl::create(uint8_t _num, const TextureHandle* _handles, const uint8_t* /*_side*/)
 	{
 		m_num = 0;
 		for (uint32_t ii = 0; ii < _num; ++ii)

src/renderer_null.cpp

@@ -134,7 +134,7 @@ namespace bgfx { namespace noop
 		{
 		}
 
-		void createFrameBuffer(FrameBufferHandle /*_handle*/, uint8_t /*_num*/, const TextureHandle* /*_textureHandles*/) BX_OVERRIDE
+		void createFrameBuffer(FrameBufferHandle /*_handle*/, uint8_t /*_num*/, const TextureHandle* /*_textureHandles*/, const uint8_t* /*_side*/) BX_OVERRIDE
 		{
 		}