EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-06-02 08:58:14
0001 //////////////////////////////////////////////////////////// 0002 // 0003 // SFML - Simple and Fast Multimedia Library 0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org) 0005 // 0006 // This software is provided 'as-is', without any express or implied warranty. 0007 // In no event will the authors be held liable for any damages arising from the use of this software. 0008 // 0009 // Permission is granted to anyone to use this software for any purpose, 0010 // including commercial applications, and to alter it and redistribute it freely, 0011 // subject to the following restrictions: 0012 // 0013 // 1. The origin of this software must not be misrepresented; 0014 // you must not claim that you wrote the original software. 0015 // If you use this software in a product, an acknowledgment 0016 // in the product documentation would be appreciated but is not required. 0017 // 0018 // 2. Altered source versions must be plainly marked as such, 0019 // and must not be misrepresented as being the original software. 0020 // 0021 // 3. This notice may not be removed or altered from any source distribution. 0022 // 0023 //////////////////////////////////////////////////////////// 0024 0025 #ifndef SFML_VERTEXBUFFER_HPP 0026 #define SFML_VERTEXBUFFER_HPP 0027 0028 //////////////////////////////////////////////////////////// 0029 // Headers 0030 //////////////////////////////////////////////////////////// 0031 #include <SFML/Graphics/Export.hpp> 0032 #include <SFML/Graphics/PrimitiveType.hpp> 0033 #include <SFML/Graphics/Drawable.hpp> 0034 #include <SFML/Window/GlResource.hpp> 0035 0036 0037 namespace sf 0038 { 0039 class RenderTarget; 0040 class Vertex; 0041 0042 //////////////////////////////////////////////////////////// 0043 /// \brief Vertex buffer storage for one or more 2D primitives 0044 /// 0045 //////////////////////////////////////////////////////////// 0046 class SFML_GRAPHICS_API VertexBuffer : public Drawable, private GlResource 0047 { 0048 public: 0049 0050 //////////////////////////////////////////////////////////// 0051 /// \brief Usage specifiers 0052 /// 0053 /// If data is going to be updated once or more every frame, 0054 /// set the usage to Stream. If data is going to be set once 0055 /// and used for a long time without being modified, set the 0056 /// usage to Static. For everything else Dynamic should be a 0057 /// good compromise. 0058 /// 0059 //////////////////////////////////////////////////////////// 0060 enum Usage 0061 { 0062 Stream, //!< Constantly changing data 0063 Dynamic, //!< Occasionally changing data 0064 Static //!< Rarely changing data 0065 }; 0066 0067 //////////////////////////////////////////////////////////// 0068 /// \brief Default constructor 0069 /// 0070 /// Creates an empty vertex buffer. 0071 /// 0072 //////////////////////////////////////////////////////////// 0073 VertexBuffer(); 0074 0075 //////////////////////////////////////////////////////////// 0076 /// \brief Construct a VertexBuffer with a specific PrimitiveType 0077 /// 0078 /// Creates an empty vertex buffer and sets its primitive type to \p type. 0079 /// 0080 /// \param type Type of primitive 0081 /// 0082 //////////////////////////////////////////////////////////// 0083 explicit VertexBuffer(PrimitiveType type); 0084 0085 //////////////////////////////////////////////////////////// 0086 /// \brief Construct a VertexBuffer with a specific usage specifier 0087 /// 0088 /// Creates an empty vertex buffer and sets its usage to \p usage. 0089 /// 0090 /// \param usage Usage specifier 0091 /// 0092 //////////////////////////////////////////////////////////// 0093 explicit VertexBuffer(Usage usage); 0094 0095 //////////////////////////////////////////////////////////// 0096 /// \brief Construct a VertexBuffer with a specific PrimitiveType and usage specifier 0097 /// 0098 /// Creates an empty vertex buffer and sets its primitive type 0099 /// to \p type and usage to \p usage. 0100 /// 0101 /// \param type Type of primitive 0102 /// \param usage Usage specifier 0103 /// 0104 //////////////////////////////////////////////////////////// 0105 VertexBuffer(PrimitiveType type, Usage usage); 0106 0107 //////////////////////////////////////////////////////////// 0108 /// \brief Copy constructor 0109 /// 0110 /// \param copy instance to copy 0111 /// 0112 //////////////////////////////////////////////////////////// 0113 VertexBuffer(const VertexBuffer& copy); 0114 0115 //////////////////////////////////////////////////////////// 0116 /// \brief Destructor 0117 /// 0118 //////////////////////////////////////////////////////////// 0119 ~VertexBuffer(); 0120 0121 //////////////////////////////////////////////////////////// 0122 /// \brief Create the vertex buffer 0123 /// 0124 /// Creates the vertex buffer and allocates enough graphics 0125 /// memory to hold \p vertexCount vertices. Any previously 0126 /// allocated memory is freed in the process. 0127 /// 0128 /// In order to deallocate previously allocated memory pass 0 0129 /// as \p vertexCount. Don't forget to recreate with a non-zero 0130 /// value when graphics memory should be allocated again. 0131 /// 0132 /// \param vertexCount Number of vertices worth of memory to allocate 0133 /// 0134 /// \return True if creation was successful 0135 /// 0136 //////////////////////////////////////////////////////////// 0137 bool create(std::size_t vertexCount); 0138 0139 //////////////////////////////////////////////////////////// 0140 /// \brief Return the vertex count 0141 /// 0142 /// \return Number of vertices in the vertex buffer 0143 /// 0144 //////////////////////////////////////////////////////////// 0145 std::size_t getVertexCount() const; 0146 0147 //////////////////////////////////////////////////////////// 0148 /// \brief Update the whole buffer from an array of vertices 0149 /// 0150 /// The \a vertex array is assumed to have the same size as 0151 /// the \a created buffer. 0152 /// 0153 /// No additional check is performed on the size of the vertex 0154 /// array, passing invalid arguments will lead to undefined 0155 /// behavior. 0156 /// 0157 /// This function does nothing if \a vertices is null or if the 0158 /// buffer was not previously created. 0159 /// 0160 /// \param vertices Array of vertices to copy to the buffer 0161 /// 0162 /// \return True if the update was successful 0163 /// 0164 //////////////////////////////////////////////////////////// 0165 bool update(const Vertex* vertices); 0166 0167 //////////////////////////////////////////////////////////// 0168 /// \brief Update a part of the buffer from an array of vertices 0169 /// 0170 /// \p offset is specified as the number of vertices to skip 0171 /// from the beginning of the buffer. 0172 /// 0173 /// If \p offset is 0 and \p vertexCount is equal to the size of 0174 /// the currently created buffer, its whole contents are replaced. 0175 /// 0176 /// If \p offset is 0 and \p vertexCount is greater than the 0177 /// size of the currently created buffer, a new buffer is created 0178 /// containing the vertex data. 0179 /// 0180 /// If \p offset is 0 and \p vertexCount is less than the size of 0181 /// the currently created buffer, only the corresponding region 0182 /// is updated. 0183 /// 0184 /// If \p offset is not 0 and \p offset + \p vertexCount is greater 0185 /// than the size of the currently created buffer, the update fails. 0186 /// 0187 /// No additional check is performed on the size of the vertex 0188 /// array, passing invalid arguments will lead to undefined 0189 /// behavior. 0190 /// 0191 /// \param vertices Array of vertices to copy to the buffer 0192 /// \param vertexCount Number of vertices to copy 0193 /// \param offset Offset in the buffer to copy to 0194 /// 0195 /// \return True if the update was successful 0196 /// 0197 //////////////////////////////////////////////////////////// 0198 bool update(const Vertex* vertices, std::size_t vertexCount, unsigned int offset); 0199 0200 //////////////////////////////////////////////////////////// 0201 /// \brief Copy the contents of another buffer into this buffer 0202 /// 0203 /// \param vertexBuffer Vertex buffer whose contents to copy into this vertex buffer 0204 /// 0205 /// \return True if the copy was successful 0206 /// 0207 //////////////////////////////////////////////////////////// 0208 bool update(const VertexBuffer& vertexBuffer); 0209 0210 //////////////////////////////////////////////////////////// 0211 /// \brief Overload of assignment operator 0212 /// 0213 /// \param right Instance to assign 0214 /// 0215 /// \return Reference to self 0216 /// 0217 //////////////////////////////////////////////////////////// 0218 VertexBuffer& operator =(const VertexBuffer& right); 0219 0220 //////////////////////////////////////////////////////////// 0221 /// \brief Swap the contents of this vertex buffer with those of another 0222 /// 0223 /// \param right Instance to swap with 0224 /// 0225 //////////////////////////////////////////////////////////// 0226 void swap(VertexBuffer& right); 0227 0228 //////////////////////////////////////////////////////////// 0229 /// \brief Get the underlying OpenGL handle of the vertex buffer. 0230 /// 0231 /// You shouldn't need to use this function, unless you have 0232 /// very specific stuff to implement that SFML doesn't support, 0233 /// or implement a temporary workaround until a bug is fixed. 0234 /// 0235 /// \return OpenGL handle of the vertex buffer or 0 if not yet created 0236 /// 0237 //////////////////////////////////////////////////////////// 0238 unsigned int getNativeHandle() const; 0239 0240 //////////////////////////////////////////////////////////// 0241 /// \brief Set the type of primitives to draw 0242 /// 0243 /// This function defines how the vertices must be interpreted 0244 /// when it's time to draw them. 0245 /// 0246 /// The default primitive type is sf::Points. 0247 /// 0248 /// \param type Type of primitive 0249 /// 0250 //////////////////////////////////////////////////////////// 0251 void setPrimitiveType(PrimitiveType type); 0252 0253 //////////////////////////////////////////////////////////// 0254 /// \brief Get the type of primitives drawn by the vertex buffer 0255 /// 0256 /// \return Primitive type 0257 /// 0258 //////////////////////////////////////////////////////////// 0259 PrimitiveType getPrimitiveType() const; 0260 0261 //////////////////////////////////////////////////////////// 0262 /// \brief Set the usage specifier of this vertex buffer 0263 /// 0264 /// This function provides a hint about how this vertex buffer is 0265 /// going to be used in terms of data update frequency. 0266 /// 0267 /// After changing the usage specifier, the vertex buffer has 0268 /// to be updated with new data for the usage specifier to 0269 /// take effect. 0270 /// 0271 /// The default primitive type is sf::VertexBuffer::Stream. 0272 /// 0273 /// \param usage Usage specifier 0274 /// 0275 //////////////////////////////////////////////////////////// 0276 void setUsage(Usage usage); 0277 0278 //////////////////////////////////////////////////////////// 0279 /// \brief Get the usage specifier of this vertex buffer 0280 /// 0281 /// \return Usage specifier 0282 /// 0283 //////////////////////////////////////////////////////////// 0284 Usage getUsage() const; 0285 0286 //////////////////////////////////////////////////////////// 0287 /// \brief Bind a vertex buffer for rendering 0288 /// 0289 /// This function is not part of the graphics API, it mustn't be 0290 /// used when drawing SFML entities. It must be used only if you 0291 /// mix sf::VertexBuffer with OpenGL code. 0292 /// 0293 /// \code 0294 /// sf::VertexBuffer vb1, vb2; 0295 /// ... 0296 /// sf::VertexBuffer::bind(&vb1); 0297 /// // draw OpenGL stuff that use vb1... 0298 /// sf::VertexBuffer::bind(&vb2); 0299 /// // draw OpenGL stuff that use vb2... 0300 /// sf::VertexBuffer::bind(NULL); 0301 /// // draw OpenGL stuff that use no vertex buffer... 0302 /// \endcode 0303 /// 0304 /// \param vertexBuffer Pointer to the vertex buffer to bind, can be null to use no vertex buffer 0305 /// 0306 //////////////////////////////////////////////////////////// 0307 static void bind(const VertexBuffer* vertexBuffer); 0308 0309 //////////////////////////////////////////////////////////// 0310 /// \brief Tell whether or not the system supports vertex buffers 0311 /// 0312 /// This function should always be called before using 0313 /// the vertex buffer features. If it returns false, then 0314 /// any attempt to use sf::VertexBuffer will fail. 0315 /// 0316 /// \return True if vertex buffers are supported, false otherwise 0317 /// 0318 //////////////////////////////////////////////////////////// 0319 static bool isAvailable(); 0320 0321 private: 0322 0323 //////////////////////////////////////////////////////////// 0324 /// \brief Draw the vertex buffer to a render target 0325 /// 0326 /// \param target Render target to draw to 0327 /// \param states Current render states 0328 /// 0329 //////////////////////////////////////////////////////////// 0330 virtual void draw(RenderTarget& target, RenderStates states) const; 0331 0332 private: 0333 0334 //////////////////////////////////////////////////////////// 0335 // Member data 0336 //////////////////////////////////////////////////////////// 0337 unsigned int m_buffer; //!< Internal buffer identifier 0338 std::size_t m_size; //!< Size in Vertexes of the currently allocated buffer 0339 PrimitiveType m_primitiveType; //!< Type of primitives to draw 0340 Usage m_usage; //!< How this vertex buffer is to be used 0341 }; 0342 0343 } // namespace sf 0344 0345 0346 #endif // SFML_VERTEXBUFFER_HPP 0347 0348 0349 //////////////////////////////////////////////////////////// 0350 /// \class sf::VertexBuffer 0351 /// \ingroup graphics 0352 /// 0353 /// sf::VertexBuffer is a simple wrapper around a dynamic 0354 /// buffer of vertices and a primitives type. 0355 /// 0356 /// Unlike sf::VertexArray, the vertex data is stored in 0357 /// graphics memory. 0358 /// 0359 /// In situations where a large amount of vertex data would 0360 /// have to be transferred from system memory to graphics memory 0361 /// every frame, using sf::VertexBuffer can help. By using a 0362 /// sf::VertexBuffer, data that has not been changed between frames 0363 /// does not have to be re-transferred from system to graphics 0364 /// memory as would be the case with sf::VertexArray. If data transfer 0365 /// is a bottleneck, this can lead to performance gains. 0366 /// 0367 /// Using sf::VertexBuffer, the user also has the ability to only modify 0368 /// a portion of the buffer in graphics memory. This way, a large buffer 0369 /// can be allocated at the start of the application and only the 0370 /// applicable portions of it need to be updated during the course of 0371 /// the application. This allows the user to take full control of data 0372 /// transfers between system and graphics memory if they need to. 0373 /// 0374 /// In special cases, the user can make use of multiple threads to update 0375 /// vertex data in multiple distinct regions of the buffer simultaneously. 0376 /// This might make sense when e.g. the position of multiple objects has to 0377 /// be recalculated very frequently. The computation load can be spread 0378 /// across multiple threads as long as there are no other data dependencies. 0379 /// 0380 /// Simultaneous updates to the vertex buffer are not guaranteed to be 0381 /// carried out by the driver in any specific order. Updating the same 0382 /// region of the buffer from multiple threads will not cause undefined 0383 /// behaviour, however the final state of the buffer will be unpredictable. 0384 /// 0385 /// Simultaneous updates of distinct non-overlapping regions of the buffer 0386 /// are also not guaranteed to complete in a specific order. However, in 0387 /// this case the user can make sure to synchronize the writer threads at 0388 /// well-defined points in their code. The driver will make sure that all 0389 /// pending data transfers complete before the vertex buffer is sourced 0390 /// by the rendering pipeline. 0391 /// 0392 /// It inherits sf::Drawable, but unlike other drawables it 0393 /// is not transformable. 0394 /// 0395 /// Example: 0396 /// \code 0397 /// sf::Vertex vertices[15]; 0398 /// ... 0399 /// sf::VertexBuffer triangles(sf::Triangles); 0400 /// triangles.create(15); 0401 /// triangles.update(vertices); 0402 /// ... 0403 /// window.draw(triangles); 0404 /// \endcode 0405 /// 0406 /// \see sf::Vertex, sf::VertexArray 0407 /// 0408 ////////////////////////////////////////////////////////////
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|