From 3dd237aefa81bf46e160009348631f381ec149cb Mon Sep 17 00:00:00 2001 From: Branimir Karadzic Date: Sat, 11 Oct 2014 10:12:27 -0700 Subject: [PATCH] Updated docs. --- include/bgfx.c99.h | 19 ++++++++ include/bgfx.h | 112 +++++++++++++++++++++++++++++++++------------ src/bgfx.cpp | 23 +++++----- src/bgfx_p.h | 29 ++++-------- 4 files changed, 122 insertions(+), 61 deletions(-) diff --git a/include/bgfx.c99.h b/include/bgfx.c99.h index bd7f46fc..27ff54b2 100644 --- a/include/bgfx.c99.h +++ b/include/bgfx.c99.h @@ -172,6 +172,15 @@ typedef struct bgfx_memory } bgfx_memory_t; +/** + */ +typedef struct bgfx_transform +{ + float* data; //< Pointer to first matrix. + uint16_t num; //< Number of matrices. + +} bgfx_transform_t; + /** * Vertex declaration. */ @@ -1195,6 +1204,16 @@ BGFX_C_API void bgfx_set_scissor_cached(uint16_t _cache); */ BGFX_C_API uint32_t bgfx_set_transform(const void* _mtx, uint16_t _num); +/** + * Reserve `_num` matrices in internal matrix cache. Pointer returned + * can be modifed until `bgfx::frame` is called. + * + * @param _transform Pointer to `Transform` structure. + * @param _num Number of matrices. + * @returns index into matrix cache. + */ +BGFX_C_API uint32_t bgfx_alloc_transform(bgfx_transform_t* _transform, uint16_t _num); + /** * Set model matrix from matrix cache for draw primitive. * diff --git a/include/bgfx.h b/include/bgfx.h index 83e2c439..1bb58a46 100644 --- a/include/bgfx.h +++ b/include/bgfx.h @@ -40,13 +40,14 @@ namespace bgfx struct RendererType { + /// Renderer type enumeration. enum Enum { - Null, - Direct3D9, - Direct3D11, - OpenGLES, - OpenGL, + Null, //< No rendering. + Direct3D9, //< Direct3D 9.0 + Direct3D11, //< Direct3D 11.0 + OpenGLES, //< OpenGL ES 2.0+ + OpenGL, //< OpenGL 2.1+ Count }; @@ -211,19 +212,48 @@ namespace bgfx /// If fatal code code is not Fatal::DebugCheck this callback is /// called on unrecoverable error. It's not safe to continue, inform /// user and terminate application from this call. + /// + /// @param _code Fatal error code. + /// @param _str More information about error. + /// virtual void fatal(Fatal::Enum _code, const char* _str) = 0; /// Return size of for cached item. Return 0 if no cached item was /// found. + /// + /// @param _id Cache id. + /// @returns Number of bytes to read. + /// virtual uint32_t cacheReadSize(uint64_t _id) = 0; /// Read cached item. + /// + /// @param _id Cache id. + /// @param _data Buffer where to read data. + /// @param _size Size of data to read. + /// + /// @returns True if data is read. + /// virtual bool cacheRead(uint64_t _id, void* _data, uint32_t _size) = 0; /// Write cached item. + /// + /// @param _id Cache id. + /// @param _data Data to write. + /// @param _size Size of data to write. + /// virtual void cacheWrite(uint64_t _id, const void* _data, uint32_t _size) = 0; /// Screenshot captured. Screenshot format is always 4-byte BGRA. + /// + /// @param _filePath File path. + /// @param _width Image width. + /// @param _height Image height. + /// @param _pitch Number of bytes to skip to next line. + /// @param _data Image data. + /// @param _size Image size. + /// @param _yflip If true image origin is bottom left. + /// virtual void screenShot(const char* _filePath, uint32_t _width, uint32_t _height, uint32_t _pitch, const void* _data, uint32_t _size, bool _yflip) = 0; /// Called when capture begins. @@ -233,6 +263,10 @@ namespace bgfx virtual void captureEnd() = 0; /// Captured frame. + /// + /// @param _data Image data. + /// @param _size Image size. + /// virtual void captureFrame(const void* _data, uint32_t _size) = 0; }; @@ -437,20 +471,38 @@ namespace bgfx /// /// @param _type Select rendering backend. When set to RendererType::Count /// default rendering backend will be selected. + /// See: `bgfx::RendererType` /// /// @param _callback Provide application specific callback interface. - /// See: CallbackI + /// See: `bgfx::CallbackI` /// /// @param _reallocator Custom allocator. When custom allocator is not /// specified, library uses default CRT allocator. The library assumes - /// custom allocator is thread safe. + /// icustom allocator is thread safe. + /// + /// @attention C99 equivalent is `bgfx_init`. /// void init(RendererType::Enum _type = RendererType::Count, CallbackI* _callback = NULL, bx::ReallocatorI* _reallocator = NULL); /// Shutdown bgfx library. + /// + /// @attention C99 equivalent is `bgfx_shutdown`. + /// void shutdown(); /// Reset graphic settings. + /// + /// @param _width Main window width. + /// @param _height Main window height. + /// @param _flags + /// - `BGFX_RESET_NONE` - No reset flags. + /// - `BGFX_RESET_FULLSCREEN` - Not supported yet. + /// - `BGFX_RESET_MSAA_X[2/4/8/16]` - Enable 2, 4, 8 or 16 x MSAA. + /// - `BGFX_RESET_VSYNC` - Enable V-Sync. + /// - `BGFX_RESET_CAPTURE` - Begin screen capture. + /// + /// @attention C99 equivalent is `bgfx_reset`. + /// void reset(uint32_t _width, uint32_t _height, uint32_t _flags = BGFX_RESET_NONE); /// Advance to next frame. When using multithreaded renderer, this call @@ -459,7 +511,9 @@ namespace bgfx /// /// @returns Current frame number. This might be used in conjunction with /// double/multi buffering data outside the library and passing it to - /// library via makeRef calls. + /// library via `bgfx::makeRef` calls. + /// + /// @attention C99 equivalent is `bgfx_frame`. /// uint32_t frame(); @@ -468,13 +522,19 @@ namespace bgfx /// @remarks /// Library must be initialized. /// + /// @attention C99 equivalent is `bgfx_get_renderer_type`. + /// RendererType::Enum getRendererType(); /// Returns renderer capabilities. /// + /// @returns Pointer to static `bgfx::Caps` structure. + /// /// @remarks /// Library must be initialized. /// + /// @attention C99 equivalent is `bgfx_get_caps`. + /// const Caps* getCaps(); /// Allocate buffer to pass to bgfx calls. Data will be freed inside bgfx. @@ -483,9 +543,9 @@ namespace bgfx /// Allocate buffer and copy data into it. Data will be freed inside bgfx. const Memory* copy(const void* _data, uint32_t _size); - /// Make reference to data to pass to bgfx. Unlike bgfx::alloc this call - /// doesn't allocate memory for data. It just copies pointer to data. - /// You must make sure data is available for at least 2 bgfx::frame calls. + /// Make reference to data to pass to bgfx. Unlike `bgfx::alloc` this call + /// doesn't allocate memory for data. It just copies pointer to data. You + /// must make sure data is available for at least 2 `bgfx::frame` calls. const Memory* makeRef(const void* _data, uint32_t _size); /// Set debug flags. @@ -1037,6 +1097,15 @@ namespace bgfx /// uint32_t setTransform(const void* _mtx, uint16_t _num = 1); + /// Reserve `_num` matrices in internal matrix cache. Pointer returned + /// can be modifed until `bgfx::frame` is called. + /// + /// @param _transform Pointer to `Transform` structure. + /// @param _num Number of matrices. + /// @returns index into matrix cache. + /// + uint32_t allocTransform(Transform* _transform, uint16_t _num); + /// Set model matrix from matrix cache for draw primitive. /// /// @param _cache Index in matrix cache. @@ -1044,23 +1113,6 @@ namespace bgfx /// void setTransform(uint32_t _cache, uint16_t _num = 1); - /// Reserve `_num` matrices in internal matrix cache. Pointer returned - /// can be modifed until `bgfx::frame` is called. - /// - /// @param _transform Pointer to `Transform` structure. - /// @param _num Number of matrices. - /// - void allocTransform(Transform* _transform, uint16_t _num); - - /// Set model matrix from `Transform` structure. - /// - /// @param _transform Pointer to `Transform` structure returned by - // `bgfx::allocTransform`. - /// @param _first First matrix. - /// @param _num Number of matrices. - /// - void setTransform(const Transform* _transform, uint32_t _first, uint16_t _num); - /// Set shader uniform parameter for draw primitive. void setUniform(UniformHandle _handle, const void* _value, uint16_t _num = 1); @@ -1151,10 +1203,10 @@ namespace bgfx /// Request screen shot. /// - /// @param _filePath Will be passed to CallbackI::screenShot callback. + /// @param _filePath Will be passed to `bgfx::CallbackI::screenShot` callback. /// /// @remarks - /// CallbackI::screenShot must be implemented. + /// `bgfx::CallbackI::screenShot` must be implemented. /// void saveScreenShot(const char* _filePath); diff --git a/src/bgfx.cpp b/src/bgfx.cpp index 1816be94..83666c8d 100644 --- a/src/bgfx.cpp +++ b/src/bgfx.cpp @@ -2592,24 +2592,18 @@ again: return s_ctx->setTransform(_mtx, _num); } + uint32_t allocTransform(Transform* _transform, uint16_t _num) + { + BGFX_CHECK_MAIN_THREAD(); + return s_ctx->allocTransform(_transform, _num); + } + void setTransform(uint32_t _cache, uint16_t _num) { BGFX_CHECK_MAIN_THREAD(); s_ctx->setTransform(_cache, _num); } - void allocTransform(Transform* _transform, uint16_t _num) - { - BGFX_CHECK_MAIN_THREAD(); - s_ctx->allocTransform(_transform, _num); - } - - void setTransform(const Transform* _transform, uint32_t _first, uint16_t _num) - { - BGFX_CHECK_MAIN_THREAD(); - s_ctx->setTransform(_transform, _first, _num); - } - void setUniform(UniformHandle _handle, const void* _value, uint16_t _num) { BGFX_CHECK_MAIN_THREAD(); @@ -3224,6 +3218,11 @@ BGFX_C_API uint32_t bgfx_set_transform(const void* _mtx, uint16_t _num) return bgfx::setTransform(_mtx, _num); } +BGFX_C_API uint32_t bgfx_alloc_transform(bgfx_transform_t* _transform, uint16_t _num) +{ + return bgfx::allocTransform( (bgfx::Transform*)_transform, _num); +} + BGFX_C_API void bgfx_set_transform_cached(uint32_t _cache, uint16_t _num) { bgfx::setTransform(_cache, _num); diff --git a/src/bgfx_p.h b/src/bgfx_p.h index 1b823f93..97b8d6d9 100644 --- a/src/bgfx_p.h +++ b/src/bgfx_p.h @@ -1248,22 +1248,18 @@ namespace bgfx return m_draw.m_matrix; } - void setTransform(uint32_t _cache, uint16_t _num) - { - m_draw.m_matrix = _cache; - m_draw.m_num = _num; - } - - void allocTransform(Transform* _transform, uint16_t _num) + uint32_t allocTransform(Transform* _transform, uint16_t _num) { uint32_t first = m_matrixCache.reserve(&_num); _transform->data = m_matrixCache.toPtr(first); _transform->num = _num; + + return first; } - void setTransform(const Transform* _transform, uint32_t _first, uint16_t _num) + void setTransform(uint32_t _cache, uint16_t _num) { - m_draw.m_matrix = m_matrixCache.fromPtr(_transform->data) + _first; + m_draw.m_matrix = _cache; m_draw.m_num = _num; } @@ -2781,21 +2777,16 @@ namespace bgfx return m_submit->setTransform(_mtx, _num); } + BGFX_API_FUNC(uint32_t allocTransform(Transform* _transform, uint16_t _num) ) + { + return m_submit->allocTransform(_transform, _num); + } + BGFX_API_FUNC(void setTransform(uint32_t _cache, uint16_t _num) ) { m_submit->setTransform(_cache, _num); } - BGFX_API_FUNC(void allocTransform(Transform* _transform, uint16_t _num) ) - { - m_submit->allocTransform(_transform, _num); - } - - BGFX_API_FUNC(void setTransform(const Transform* _transform, uint32_t _first, uint16_t _num) ) - { - m_submit->setTransform(_transform, _first, _num); - } - BGFX_API_FUNC(void setUniform(UniformHandle _handle, const void* _value, uint16_t _num) ) { UniformRef& uniform = m_uniformRef[_handle.idx];