From 4c4be0a750828670b0439ef69c2984e42d0a6266 Mon Sep 17 00:00:00 2001 From: Robert Osfield Date: Mon, 13 Sep 2004 16:10:59 +0000 Subject: [PATCH] From Paul Martz, typo and spelling fixes --- include/osg/Switch | 37 ++++----- include/osg/TexEnv | 15 ++-- include/osg/TexEnvCombine | 20 ++--- include/osg/TexGen | 22 ++--- include/osg/TexGenNode | 8 +- include/osg/TexMat | 23 +++--- include/osg/Texture | 163 ++++++++++++++++++++------------------ include/osg/Texture1D | 71 +++++++++-------- include/osg/Texture2D | 71 +++++++++-------- include/osg/Texture3D | 84 ++++++++++---------- 10 files changed, 266 insertions(+), 248 deletions(-) diff --git a/include/osg/Switch b/include/osg/Switch index 97e84adae..0a2a05945 100644 --- a/include/osg/Switch +++ b/include/osg/Switch @@ -18,10 +18,10 @@ namespace osg { -/** Switch is a Group node which allows switching between children. - Typical uses would be for objects which might need to be rendered - differently at different times, for instance a switch could be used - to represent the different states of a traffic light. +/** Switch is a Group node that allows switching between children. + * Typical uses would be for objects which might need to be rendered + * differently at different times, for instance a switch could be used + * to represent the different states of a traffic light. */ class SG_EXPORT Switch : public Group { @@ -30,7 +30,7 @@ class SG_EXPORT Switch : public Group Switch(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ Switch(const Switch&,const CopyOp& copyop=CopyOp::SHALLOW_COPY); META_Node(osg, Switch); @@ -59,20 +59,20 @@ class SG_EXPORT Switch : public Group bool getChildValue(const Node* child) const; - /** Set all the children off (false), and set the new default child value to off (false).*/ + /** Set all the children off (false), and set the new default child + * value to off (false). */ bool setAllChildrenOff(); - /** Set all the children on (true), and set the new default child value to on (true).*/ + /** Set all the children on (true), and set the new default child + * value to on (true). */ bool setAllChildrenOn(); - /** Set a single child to be on, switch off all other children.*/ + /** Set a single child on, switch off all other children. */ bool setSingleChildOn(unsigned int pos); #ifdef USE_DEPRECATED_API - /** - * Special values for the Switch. Use these if you want to - * turn on/off all child nodes. - */ + /** Special values for the Switch. Use these if you want to + * turn on/off all child nodes. */ enum Values { /** All children turned on. */ ALL_CHILDREN_ON=-1, @@ -82,17 +82,12 @@ class SG_EXPORT Switch : public Group MULTIPLE_CHILDREN_ON=-3 }; - /** - * Selects the active child Node or enables a special - * SwitchType mode. - * @param value the number of the active child - * (first child == number 0) or SwitchType. Invalid values - * will be ignored. - */ + /** Selects the active child Node or enables a special SwitchType mode. + * @param value the number of the active child (first child == number + * 0) or SwitchType. Invalid values will be ignored. */ void setValue(int value); int getValue() const; - #endif typedef std::vector ValueList; @@ -103,7 +98,7 @@ class SG_EXPORT Switch : public Group virtual ~Switch() {} - // this is effectively a bit mask. + // This is effectively a bit mask. bool _newChildDefaultValue; ValueList _values; }; diff --git a/include/osg/TexEnv b/include/osg/TexEnv index a4ad20363..18e0f1a84 100644 --- a/include/osg/TexEnv +++ b/include/osg/TexEnv @@ -20,7 +20,8 @@ namespace osg { -/** TexEnv - encapsulates the OpenGL glTexEnv (texture environment) state.*/ +/** TexEnv encapsulates the OpenGL glTexEnv (texture environment) state. +*/ class SG_EXPORT TexEnv : public StateAttribute { public : @@ -35,7 +36,7 @@ class SG_EXPORT TexEnv : public StateAttribute TexEnv(Mode mode=MODULATE); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ TexEnv(const TexEnv& texenv,const CopyOp& copyop=CopyOp::SHALLOW_COPY): StateAttribute(texenv,copyop), _mode(texenv._mode), @@ -46,18 +47,18 @@ class SG_EXPORT TexEnv : public StateAttribute virtual bool isTextureAttribute() const { return true; } - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& sa) const { - // check the types are equal and then create the rhs variable - // used by the COMPARE_StateAttribute_Paramter macro's below. + // Check for equal types, then create the rhs variable + // used by the COMPARE_StateAttribute_Paramter macros below. COMPARE_StateAttribute_Types(TexEnv,sa) - // compare each paramter in turn against the rhs. + // Compare each parameter in turn against the rhs. COMPARE_StateAttribute_Parameter(_mode) COMPARE_StateAttribute_Parameter(_color) - return 0; // passed all the above comparison macro's, must be equal. + return 0; // Passed all the above comparison macros, so must be equal. } diff --git a/include/osg/TexEnvCombine b/include/osg/TexEnvCombine index fc99f1287..f9bdc323a 100644 --- a/include/osg/TexEnvCombine +++ b/include/osg/TexEnvCombine @@ -19,7 +19,7 @@ #include #include -// if not defined by gl.h use the definition found in: +// If not defined by gl.h use the definition found in: // http://oss.sgi.com/projects/ogl-sample/registry/ARB/texture_env_combine.txt #ifndef GL_ARB_texture_env_combine #define GL_COMBINE_ARB 0x8570 @@ -57,14 +57,15 @@ namespace osg { -/** TexEnvCombine - encapsulates the OpenGL glTexEnvCombine (texture environment) state.*/ +/** TexEnvCombine encapsulates the OpenGL glTexEnvCombine (texture + * environment) state. */ class SG_EXPORT TexEnvCombine : public StateAttribute { public : TexEnvCombine(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ TexEnvCombine(const TexEnvCombine& texenv,const CopyOp& copyop=CopyOp::SHALLOW_COPY): StateAttribute(texenv,copyop), _needsTexEnvCrossbar(texenv._needsTexEnvCrossbar), @@ -92,14 +93,14 @@ class SG_EXPORT TexEnvCombine : public StateAttribute virtual bool isTextureAttribute() const { return true; } - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& sa) const { - // check the types are equal and then create the rhs variable - // used by the COMPARE_StateAttribute_Paramter macro's below. + // Check for equal types, then create the rhs variable + // used by the COMPARE_StateAttribute_parameter macros below. COMPARE_StateAttribute_Types(TexEnvCombine,sa) - // compare each paramter in turn against the rhs. + // Compare each parameter in turn against the rhs. COMPARE_StateAttribute_Parameter(_needsTexEnvCrossbar) COMPARE_StateAttribute_Parameter(_combine_RGB) COMPARE_StateAttribute_Parameter(_combine_Alpha) @@ -119,7 +120,7 @@ class SG_EXPORT TexEnvCombine : public StateAttribute COMPARE_StateAttribute_Parameter(_scale_Alpha) COMPARE_StateAttribute_Parameter(_constantColor) - return 0; // passed all the above comparison macro's, must be equal. + return 0; // Passed all the above comparison macros, so must be equal. } @@ -207,7 +208,8 @@ class SG_EXPORT TexEnvCombine : public StateAttribute void setConstantColor( const Vec4& color ) { _constantColor = color; } const Vec4& getConstantColor() const { return _constantColor; } - /** Set the constant color attribute up to light direction to be used in DOT3 combine operation.*/ + /** Set the constant color attribute to the given light direction + * for use with DOT3 combine operation. */ void setConstantColorAsLightDirection(const Vec3& direction) { _constantColor.set((direction.x()+1.0f)*0.5f,(direction.y()+1.0f)*0.5f,(direction.z()+1.0f)*0.5f,1.0f); diff --git a/include/osg/TexGen b/include/osg/TexGen index c04e4f7c7..f0109e9fc 100644 --- a/include/osg/TexGen +++ b/include/osg/TexGen @@ -27,14 +27,15 @@ namespace osg { #define GL_REFLECTION_MAP_ARB 0x8512 #endif -/** TexGen - encapsulates the OpenGL glTexGen (texture coordinate generation) state.*/ +/** TexGen encapsulates the OpenGL glTexGen (texture coordinate generation) + * state.*/ class SG_EXPORT TexGen : public StateAttribute { public : TexGen(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ TexGen(const TexGen& texgen,const CopyOp& copyop=CopyOp::SHALLOW_COPY): StateAttribute(texgen,copyop), _mode(texgen._mode), @@ -47,21 +48,21 @@ class SG_EXPORT TexGen : public StateAttribute virtual bool isTextureAttribute() const { return true; } - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& sa) const { - // check the types are equal and then create the rhs variable - // used by the COMPARE_StateAttribute_Paramter macro's below. + // Check for equal types, then create the rhs variable + // used by the COMPARE_StateAttribute_Paramter macros below. COMPARE_StateAttribute_Types(TexGen,sa) - // compare each paramter in turn against the rhs. + // Compare each parameter in turn against the rhs. COMPARE_StateAttribute_Parameter(_mode) COMPARE_StateAttribute_Parameter(_plane_s) COMPARE_StateAttribute_Parameter(_plane_t) COMPARE_StateAttribute_Parameter(_plane_r) COMPARE_StateAttribute_Parameter(_plane_q) - return 0; // passed all the above comparison macro's, must be equal. + return 0; // Passed all the above comparison macros, so must be equal. } virtual bool getModeUsage(ModeUsage& usage) const @@ -71,7 +72,7 @@ class SG_EXPORT TexGen : public StateAttribute // Not happy with turning all tex gen paramters on // as the OSG currently only supports 2D textures and therefore - // only S and T will only be required, R&Q would be redundant... + // only S and T will be required, R&Q would be redundant... // So commenting out the following until OSG supports 3D textures. // I plan to revamp the OpenGL state management later so will // tidy up then. Robert Osfield. Jan 2001. @@ -99,7 +100,7 @@ class SG_EXPORT TexGen : public StateAttribute Mode getMode() const { return _mode; } enum Coord { - S, T, R, Q + S, T, R, Q }; void setPlane(Coord which, const Plane& plane); @@ -114,7 +115,8 @@ class SG_EXPORT TexGen : public StateAttribute Mode _mode; - /// additional texgen coefficents for GL_OBJECT_PLANE or GL_EYE_PLANE, + /** Additional texgen coefficents for GL_OBJECT_PLANE or + * GL_EYE_PLANE, */ Plane _plane_s, _plane_t, _plane_r, _plane_q; }; diff --git a/include/osg/TexGenNode b/include/osg/TexGenNode index 001e15171..60a8d25a1 100644 --- a/include/osg/TexGenNode +++ b/include/osg/TexGenNode @@ -19,7 +19,7 @@ namespace osg { -/** Node for defining the position of TexGen in the scene.*/ +/** Node for defining the position of TexGen in the scene. */ class SG_EXPORT TexGenNode : public Group { @@ -37,13 +37,13 @@ class SG_EXPORT TexGenNode : public Group unsigned int getTextureUnit() const { return _textureUnit; } - /** Set the TexGen.*/ + /** Set the TexGen. */ void setTexGen(TexGen* texgen); - /** Get the TexGen.*/ + /** Get the TexGen. */ inline TexGen* getTexGen() { return _texgen.get(); } - /** Get the const TexGen.*/ + /** Get the const TexGen. */ inline const TexGen* getTexGen() const { return _texgen.get(); } diff --git a/include/osg/TexMat b/include/osg/TexMat index d5194c955..368e1803b 100644 --- a/include/osg/TexMat +++ b/include/osg/TexMat @@ -19,14 +19,15 @@ namespace osg { -/** Texture Matrix state class for encapsulating OpenGL texture matrix functionality.*/ +/** A texture matrix state class that encapsulates OpenGL texture matrix + * functionality. */ class SG_EXPORT TexMat : public StateAttribute { public : TexMat(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ TexMat(const TexMat& texmat,const CopyOp& copyop=CopyOp::SHALLOW_COPY): StateAttribute(texmat,copyop), _matrix(texmat._matrix) {} @@ -35,29 +36,29 @@ class SG_EXPORT TexMat : public StateAttribute virtual bool isTextureAttribute() const { return true; } - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& sa) const { - // check the types are equal and then create the rhs variable - // used by the COMPARE_StateAttribute_Paramter macro's below. + // Check for equal types, then create the rhs variable + // used by the COMPARE_StateAttribute_Paramter macros below. COMPARE_StateAttribute_Types(TexMat,sa) - // compare each paramter in turn against the rhs. + // Compare each parameter in turn against the rhs. COMPARE_StateAttribute_Parameter(_matrix) - return 0; // passed all the above comparison macro's, must be equal. + return 0; // Passed all the above comparison macros, so must be equal. } - /** Set the texture matrix */ + /** Set the texture matrix */ inline void setMatrix(const Matrix& matrix) { _matrix = matrix; } - /** Get the texture matrix */ + /** Get the texture matrix */ inline Matrix& getMatrix() { return _matrix; } - /** Get the const texture matrix */ + /** Get the const texture matrix */ inline const Matrix& getMatrix() const { return _matrix; } - /** apply as OpenGL texture matrix.*/ + /** Apply texture matrix to OpenGL state. */ virtual void apply(State& state) const; protected: diff --git a/include/osg/Texture b/include/osg/Texture index be759efc7..633f3c322 100644 --- a/include/osg/Texture +++ b/include/osg/Texture @@ -29,7 +29,7 @@ #include #endif -// if not defined by gl.h use the definition found in: +// If not defined by gl.h use the definition found in: // http://oss.sgi.com/projects/ogl-sample/registry/EXT/texture_filter_anisotropic.txt #ifndef GL_TEXTURE_MAX_ANISOTROPY_EXT #define GL_TEXTURE_MAX_ANISOTROPY_EXT 0x84FE @@ -162,7 +162,9 @@ namespace osg { -/** Texture base class which encapsulates OpenGl texture functionality which common betweent the various types of OpenGL textures.*/ +/** Texture pure virtual base class that encapsulates OpenGl texture + * functionality common to the various types of OSG textures. +*/ class SG_EXPORT Texture : public osg::StateAttribute { @@ -170,7 +172,7 @@ class SG_EXPORT Texture : public osg::StateAttribute Texture(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ Texture(const Texture& text,const CopyOp& copyop=CopyOp::SHALLOW_COPY); virtual osg::Object* cloneType() const = 0; @@ -196,20 +198,20 @@ class SG_EXPORT Texture : public osg::StateAttribute MIRROR = GL_MIRRORED_REPEAT_IBM }; - /** Set the texture wrap mode.*/ + /** Sets the texture wrap mode. */ void setWrap(WrapParameter which, WrapMode wrap); - /** Get the texture wrap mode.*/ + /** Gets the texture wrap mode. */ WrapMode getWrap(WrapParameter which) const; - /** Set the border color for this texture. Makes difference only if - * wrap mode is CLAMP_TO_BORDER */ + /** Sets the border color. Only used when wrap mode is + * CLAMP_TO_BORDER. */ void setBorderColor(const Vec4& color) { _borderColor = color; dirtyTextureParameters(); } - - /** Get the border color for this texture.*/ + + /** Gets the border color. */ const Vec4& getBorderColor() const { return _borderColor; } - /** Set the border width.*/ + /** Sets the border width. */ void setBorderWidth(GLint width) { _borderWidth = width; dirtyTextureParameters(); } GLint getBorderWidth() const { return _borderWidth; } @@ -229,41 +231,44 @@ class SG_EXPORT Texture : public osg::StateAttribute }; - /** Set the texture filter mode.*/ + /** Sets the texture filter mode. */ void setFilter(FilterParameter which, FilterMode filter); - /** Get the texture filter mode.*/ + /** Gets the texture filter mode. */ FilterMode getFilter(FilterParameter which) const; - /** Set the maximum anisotropy value, default value is 1.0 for - * no anisotropic filtering. If hardware does not support anisotropic - * filtering then normal filtering is used, equivilant to a max anisotropy value of 1.0. - * valid range is 1.0f upwards. The maximum value depends on the graphics - * system being used.*/ + /** Sets the maximum anisotropy value, default value is 1.0 for no + * anisotropic filtering. If hardware does not support anisotropic + * filtering, use normal filtering (equivilant to a max anisotropy + * value of 1.0. Valid range is 1.0f upwards. The maximum value + * depends on the graphics system. */ void setMaxAnisotropy(float anis); - /** Get the maximum anisotropy value.*/ + /** Gets the maximum anisotropy value. */ inline float getMaxAnisotropy() const { return _maxAnisotropy; } - /** Set the hint of whether to use hardware mip map generation where available.*/ + /** Sets the hardware mipmap generation hint. If enabled, it will + * only be used if supported in the graphics system. */ inline void setUseHardwareMipMapGeneration(bool useHardwareMipMapGeneration) { _useHardwareMipMapGeneration = useHardwareMipMapGeneration; } - /** Get the hint of whether to use hardware mip map generation where available.*/ + /** Gets the hardware mipmap generation hint. */ inline bool getUseHardwareMipMapGeneration() const { return _useHardwareMipMapGeneration; } - /** Set the automatic unreference of image data after the texture has been set up in apply, on (true) or off (false). - * If the image data is only referened by this Texture then the image data will be autoamtically deleted.*/ + /** Sets whether or not the apply() function will unreference the image + * data. If enabled, and the image data is only referened by this + * Texture, apply() will delete the image data. */ inline void setUnRefImageDataAfterApply(bool flag) { _unrefImageDataAfterApply = flag; } - /** Get the automatic unreference of image data after the texture has been set up in apply.*/ + /** Gets whether or not apply() unreferences image data. */ inline bool getUnRefImageDataAfterApply() const { return _unrefImageDataAfterApply; } - /** Set whether to use client storage of the texture where supported by OpenGL drivers. - * Note, if UseClientStorageHint is set, and the OpenGL drivers support it, the osg::Image(s) associated with - * this texture cannot be deleted, so the UnRefImageDataAfterApply flag is then ignored.*/ + /** Sets whether to use client storage for the texture, if supported + * by the graphics system. Note: If enabled, and the graphics system + * supports it, the osg::Image(s) associated with this texture cannot + * be deleted, so the UnRefImageDataAfterApply flag would be ignored. */ inline void setClientStorageHint(bool flag) { _clientStorageHint = flag; } - - /** Get whether to use client storage of the texture where supported by OpenGL drivers.*/ + + /** Gets whether to use client storage for the texture. */ inline bool getClientStorageHint() const { return _clientStorageHint; } enum InternalFormatMode { @@ -275,26 +280,24 @@ class SG_EXPORT Texture : public osg::StateAttribute USE_S3TC_DXT5_COMPRESSION }; - /** Set the internal format mode. - * Note, If the mode is set USE_IMAGE_DATA_FORMAT, USE_ARB_COMPRESSION, - * USE_S3TC_COMPRESSION the internalFormat is automatically selected, - * and will overwrite the previous _internalFormat. - */ + /** Sets the internal texture format mode. Note: If the texture format is + * USE_IMAGE_DATA_FORMAT, USE_ARB_COMPRESSION, or USE_S3TC_COMPRESSION, + * the internal format mode is set automatically and will overwrite the + * previous _internalFormat. */ inline void setInternalFormatMode(InternalFormatMode mode) { _internalFormatMode = mode; } - /** Get the internal format mode.*/ + /** Gets the internal texture format mode. */ inline InternalFormatMode getInternalFormatMode() const { return _internalFormatMode; } - /** Set the internal format to use when creating OpenGL textures. - * Also sets the internalFormatMode to USE_USER_DEFINED_FORMAT. - */ + /** Sets the internal texture format. Implicitly sets the + * internalFormatMode to USE_USER_DEFINED_FORMAT. */ inline void setInternalFormat(GLint internalFormat) { _internalFormatMode = USE_USER_DEFINED_FORMAT; _internalFormat = internalFormat; } - /** Get the internal format to use when creating OpenGL textures.*/ + /** Gets the internal texture format. */ inline GLint getInternalFormat() const { if (_internalFormat==0) computeInternalFormat(); return _internalFormat; } bool isCompressedInternalFormat() const; @@ -302,32 +305,35 @@ class SG_EXPORT Texture : public osg::StateAttribute class TextureObject; - /** Get the handle to the texture object for the current context.*/ + /** Returns a pointer to the texture object for the current context. */ inline TextureObject* getTextureObject(unsigned int contextID) const { return _textureObjectBuffer[contextID].get(); } - /** Force a recompile on next apply() of associated OpenGL texture objects.*/ + /** Forces a recompile on next apply() of associated OpenGL texture + * objects. */ void dirtyTextureObject(); - /** return true if the texture objects for all the required graphics contexts are loaded.*/ + /** Returns true if the texture objects for all the required graphics + * contexts are loaded. */ bool areAllTextureObjectsLoaded() const; - /** get the dirty flag for the current contextID.*/ + /** Gets the dirty flag for the current contextID. */ inline unsigned int& getTextureParameterDirty(unsigned int contextID) const { return _texParametersDirtyList[contextID]; } - /** Force a resetting on next apply() of associated OpenGL texture parameters.*/ + /** Force a reset on next apply() of associated OpenGL texture + * parameters. */ void dirtyTextureParameters(); - // set mode of GL_TEXTURE_COMPARE_MODE_ARB to GL_COMPARE_R_TO_TEXTURE_ARB - // See http://oss.sgi.com/projects/ogl-sample/registry/ARB/shadow.txt + /** Sets GL_TEXTURE_COMPARE_MODE_ARB to GL_COMPARE_R_TO_TEXTURE_ARB + * See http://oss.sgi.com/projects/ogl-sample/registry/ARB/shadow.txt. */ void setShadowComparison(bool flag) { _use_shadow_comparison = flag; } enum ShadowCompareFunc { @@ -335,7 +341,7 @@ class SG_EXPORT Texture : public osg::StateAttribute GEQUAL = GL_GEQUAL }; - // set shadow texture comparison function + /** Sets shadow texture comparison function. */ void setShadowCompareFunc(ShadowCompareFunc func) { _shadow_compare_func = func; } ShadowCompareFunc getShadowCompareFunc() { return _shadow_compare_func; } @@ -345,43 +351,43 @@ class SG_EXPORT Texture : public osg::StateAttribute ALPHA = GL_ALPHA }; - // set shadow texture mode after comparison + /** Sets shadow texture mode after comparison. */ void setShadowTextureMode(ShadowTextureMode mode) { _shadow_texture_mode = mode; } ShadowTextureMode getShadowTextureMode() { return _shadow_texture_mode; } - // set value of TEXTURE_COMPARE_FAIL_VALUE_ARB texture parameter - // http://oss.sgi.com/projects/ogl-sample/registry/ARB/shadow_ambient.txt + /** Sets the TEXTURE_COMPARE_FAIL_VALUE_ARB texture parameter. See + * http://oss.sgi.com/projects/ogl-sample/registry/ARB/shadow_ambient.txt. */ void setShadowAmbient(float shadow_ambient) { _shadow_ambient = shadow_ambient; } float getShadowAmbient() { return _shadow_ambient; } - /** Set the texture image for specified face. */ + /** Sets the texture image for the specified face. */ virtual void setImage(unsigned int face, Image* image) = 0; - /** Get the texture image for specified face. */ + /** Gets the texture image for the specified face. */ virtual Image* getImage(unsigned int face) = 0; - /** Get the const texture image for specified face. */ + /** Gets the const texture image for specified face. */ virtual const Image* getImage(unsigned int face) const = 0; - /** Get the number of images that can be assigned to the Texture. */ + /** Gets the number of images that can be assigned to this Texture. */ virtual unsigned int getNumImages() const = 0; - /** Texture is pure virtual base class, apply must be overriden. */ + /** Texture is a pure virtual base class, apply must be overriden. */ virtual void apply(State& state) const = 0; /** Calls apply(state) to compile the texture. */ virtual void compileGLObjects(State& state) const; - /** release an OpenGL objects in specified graphics context if State - object is passed, otherwise release OpenGL objexts for all graphics context if - State object pointer NULL.*/ + /** If State is non-zero, this function releases OpenGL objects for + * the specified graphics context. Otherwise, releases OpenGL objexts + * for all graphics contexts. */ virtual void releaseGLObjects(State* state=0) const; - /** Extensions class which encapsulates the querring of extensions and - * associated function pointers, and provide convinience wrappers to - * check for the extensions or use the associated functions.*/ + /** Encapsulates queries of extension availability, obtains extension + * function pointers, and provides convinience wrappers for + * calling extension functions. */ class SG_EXPORT Extensions : public osg::Referenced { public: @@ -468,26 +474,26 @@ class SG_EXPORT Texture : public osg::StateAttribute }; - /** Function to call to get the extension of a specified context. - * If the Exentsion object for that context has not yet been created then - * and the 'createIfNotInitalized' flag been set to false then returns NULL. - * If 'createIfNotInitalized' is true then the Extensions object is - * automatically created. However, in this case the extension object - * only be created with the graphics context associated with ContextID..*/ + /** Gets the extension for the specified context. Creates the + * Extensions object for that context if it doesn't exist. + * Returns NULL if the Extensions object for the context doesn't + * exist and the createIfNotInitalized flag is false. */ static Extensions* getExtensions(unsigned int contextID,bool createIfNotInitalized); - /** setExtensions allows users to override the extensions across graphics contexts. - * typically used when you have different extensions supported across graphics pipes - * but need to ensure that they all use the same low common denominator extensions.*/ + /** Overrides Extensions objects across graphics contexts. Typically + * used to ensure the same lowest common denominator of extensions + * on sustems with different graphics pipes. */ static void setExtensions(unsigned int contextID,Extensions* extensions); - /** Helper method which does the creation of the texture itself, but does not set or use texture binding. - * Note, do not call this method directly unless you are implementing your own Subload callback*/ + /** Helper method. Creates the texture, but doesn't set or use a + * texture binding. Note: Don't call this method directly unless + * you're implementing a subload callback. */ void applyTexImage2D_load(State& state, GLenum target, const Image* image, GLsizei width, GLsizei height,GLsizei numMipmapLevels) const; - /** Helper method which subloads images to the texture itself, but does not set or use texture binding. - * Note, do not call this method directly unless you are implementing your own Subload callback*/ + /** Helper method. Subloads images into the texture, but doesn't set + * or use a texture binding. Note: Don't call this method directly + * unless you're implementing a subload callback. */ void applyTexImage2D_subload(State& state, GLenum target, const Image* image, GLsizei width, GLsizei height, GLint inInternalFormat, GLsizei numMipmapLevels) const; protected : @@ -502,12 +508,12 @@ class SG_EXPORT Texture : public osg::StateAttribute bool isCompressedInternalFormat(GLint internalFormat) const; - /** Helper method which does setting of texture paramters. */ + /** Helper method. Sets texture paramters. */ void applyTexParameters(GLenum target, State& state) const; - - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + + /** Returns -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ int compareTexture(const Texture& rhs) const; typedef buffered_value TexParameterDirtyList; @@ -636,7 +642,8 @@ class SG_EXPORT Texture : public osg::StateAttribute typedef std::list< ref_ptr > TextureObjectList; typedef std::map TextureObjectListMap; - /** take the active texture objects from the Texture and place them in the specified TextureObjectListMap.*/ + /** Takes the active texture objects from the Texture and places them + * in the specified TextureObjectListMap. */ void takeTextureObjects(TextureObjectListMap& toblm); typedef buffered_object< ref_ptr > TextureObjectBuffer; @@ -695,7 +702,7 @@ class SG_EXPORT Texture : public osg::StateAttribute double getExpiryDelay() const { return _expiryDelay; } - // how long to keep unsed texture objects around for before deleting. + /** How long to keep unused texture objects before deletion. */ double _expiryDelay; TextureObjectListMap _textureObjectListMap; diff --git a/include/osg/Texture1D b/include/osg/Texture1D index 1a3c76366..903d0be41 100644 --- a/include/osg/Texture1D +++ b/include/osg/Texture1D @@ -20,7 +20,9 @@ namespace osg { -/** Texture state class which encapsulates OpenGl 1D texture functionality.*/ +/** Encapsulates OpenGl 1D texture functionality. Doesn't support cube maps, + * so ignore \a face parameters. +*/ class SG_EXPORT Texture1D : public Texture { @@ -28,12 +30,12 @@ class SG_EXPORT Texture1D : public Texture Texture1D(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ Texture1D(const Texture1D& text,const CopyOp& copyop=CopyOp::SHALLOW_COPY); META_StateAttribute(osg, Texture1D,TEXTURE); - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& rhs) const; virtual bool getModeUsage(ModeUsage& usage) const @@ -42,13 +44,13 @@ class SG_EXPORT Texture1D : public Texture return true; } - /** Set the texture image. */ + /** Sets the texture image. */ void setImage(Image* image); - /** Get the texture image. */ + /** Gets the texture image. */ Image* getImage() { return _image.get(); } - /** Get the const texture image. */ + /** Gets the const texture image. */ inline const Image* getImage() const { return _image.get(); } inline unsigned int& getModifiedTag(unsigned int contextID) const @@ -58,27 +60,27 @@ class SG_EXPORT Texture1D : public Texture } - /** Set the texture image, ignoring face. as there is only one image*/ + /** Sets the texture image, ignoring face. */ virtual void setImage(unsigned int, Image* image) { setImage(image); } - /** Get the texture image, ignoring face value as there is only one image. */ + /** Gets the texture image, ignoring face. */ virtual Image* getImage(unsigned int) { return _image.get(); } - /** Get the const texture image , ignoring face value as there is only one image. */ + /** Gets the const texture image, ignoring face. */ virtual const Image* getImage(unsigned int) const { return _image.get(); } - /** Get the number of images that can be assigned to the Texture. */ + /** Gets the number of images that can be assigned to the Texture. */ virtual unsigned int getNumImages() const { return 1; } - /** Set the texture width and height. If width or height are zero then - * the repsective size value is calculated from the source image sizes. */ + /** Sets the texture width. If width is zero, calculate the value + * from the source image width. */ inline void setTextureSize(int width) const { _textureWidth = width; } - /** Get the texture subload width. */ + /** Gets the texture subload width. */ inline void getTextureSize(int& width) const { width = _textureWidth; @@ -99,29 +101,30 @@ class SG_EXPORT Texture1D : public Texture const SubloadCallback* getSubloadCallback() const { return _subloadCallback.get(); } - /** Set the number of mip map levels the the texture has been created with, - should only be called within an osg::Texuture::apply() and custom OpenGL texture load.*/ + /** Helper function. Sets the number of mipmap levels created for this + * texture. Should only be called within an osg::Texuture::apply(), or + * during a custom OpenGL texture load. */ void setNumMipmapLevels(unsigned int num) const { _numMipmapLevels=num; } - /** Get the number of mip map levels the the texture has been created with.*/ + /** Gets the number of mipmap levels created. */ unsigned int getNumMipmapLevels() const { return _numMipmapLevels; } - - /** Copy pixels into a 1D texture image.As per glCopyTexImage1D. + + /** Copies pixels into a 1D texture image, as per glCopyTexImage1D. * Creates an OpenGL texture object from the current OpenGL background - * framebuffer contents at pos \a x, \a y with width \a width. \a width must be a power of two. - */ + * framebuffer contents at position \a x, \a y with width \a width. + * \a width must be a power of two. */ void copyTexImage1D(State& state, int x, int y, int width); - /** Copy a one-dimensional texture subimage. As per glCopyTexSubImage1D. - * Updates portion of an existing OpenGL texture object from the current OpenGL background - * framebuffer contents at pos \a x, \a y with width \a width. - */ + /** Copies a one-dimensional texture subimage, as per + * glCopyTexSubImage1D. Updates a portion of an existing OpenGL + * texture object from the current OpenGL background framebuffer + * contents at position \a x, \a y with width \a width. */ void copyTexSubImage1D(State& state, int xoffset, int x, int y, int width); - /** On first apply (unless already compiled), create the minmapped - * texture and bind it, subsequent apply will simple bind to texture.*/ + /** Bind the texture object. If the texture object hasn't already been + * compiled, create the texture mipmap levels. */ virtual void apply(State& state) const; protected : @@ -130,21 +133,21 @@ class SG_EXPORT Texture1D : public Texture virtual void computeInternalFormat() const; - /** Helper method which does the creation of the texture itself, and - * does not set or use texture binding. */ + /** Helper method. Createa the texture without setting or using a + * texture binding. */ void applyTexImage1D(GLenum target, Image* image, State& state, GLsizei& width, GLsizei& numMipmapLevels) const; - // not ideal that _image is mutable, but its required since - // Image::ensureDimensionsArePowerOfTwo() can only be called - // in a valid OpenGL context, a therefore within an Texture::apply - // which is const... + /** It's not ideal that _image is mutable, but it's required since + * Image::ensureDimensionsArePowerOfTwo() can only be called in a + * valid OpenGL context, and therefore within Texture::apply, which + * is const. */ mutable ref_ptr _image; - // subloaded images can have different texture and image sizes. + /** Subloaded images can have different texture and image sizes. */ mutable GLsizei _textureWidth; - // number of mip map levels the the texture has been created with, + /** Number of mipmap levels created. */ mutable GLsizei _numMipmapLevels; ref_ptr _subloadCallback; diff --git a/include/osg/Texture2D b/include/osg/Texture2D index f5afb31fc..cc01a504d 100644 --- a/include/osg/Texture2D +++ b/include/osg/Texture2D @@ -18,7 +18,9 @@ namespace osg { -/** Texture state class which encapsulates OpenGl texture functionality.*/ +/** Encapsulates OpenGl 2D texture functionality. Doesn't support cube maps, + * so ignore \a face parameters. +*/ class SG_EXPORT Texture2D : public Texture { @@ -28,12 +30,12 @@ class SG_EXPORT Texture2D : public Texture Texture2D(Image* image); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ Texture2D(const Texture2D& text,const CopyOp& copyop=CopyOp::SHALLOW_COPY); META_StateAttribute(osg, Texture2D,TEXTURE); - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& rhs) const; virtual bool getModeUsage(ModeUsage& usage) const @@ -42,13 +44,13 @@ class SG_EXPORT Texture2D : public Texture return true; } - /** Set the texture image. */ + /** Sets the texture image. */ void setImage(Image* image); - /** Get the texture image. */ + /** Gets the texture image. */ Image* getImage() { return _image.get(); } - /** Get the const texture image. */ + /** Gets the const texture image. */ inline const Image* getImage() const { return _image.get(); } inline unsigned int& getModifiedTag(unsigned int contextID) const @@ -58,21 +60,21 @@ class SG_EXPORT Texture2D : public Texture } - /** Set the texture image, ignoring face. as there is only one image*/ + /** Sets the texture image, ignoring face. */ virtual void setImage(unsigned int, Image* image) { setImage(image); } - /** Get the texture image, ignoring face value as there is only one image. */ + /** Gets the texture image, ignoring face. */ virtual Image* getImage(unsigned int) { return _image.get(); } - /** Get the const texture image , ignoring face value as there is only one image. */ + /** Gets the const texture image, ignoring face. */ virtual const Image* getImage(unsigned int) const { return _image.get(); } - /** Get the number of images that can be assigned to the Texture. */ + /** Gets the number of images that can be assigned to the Texture. */ virtual unsigned int getNumImages() const { return 1; } - /** Set the texture width and height. If width or height are zero then - * the repsective size value is calculated from the source image sizes. */ + /** Sets the texture width and height. If width or height are zero, + * calculate the respective value from the source image size. */ inline void setTextureSize(int width, int height) const { _textureWidth = width; @@ -82,7 +84,7 @@ class SG_EXPORT Texture2D : public Texture int getTextureWidth() const { return _textureWidth; } int getTextureHeight() const { return _textureHeight; } - // deprecated. + /** Deprecated. */ inline void getTextureSize(int& width, int& height) const { width = _textureWidth; @@ -104,32 +106,33 @@ class SG_EXPORT Texture2D : public Texture const SubloadCallback* getSubloadCallback() const { return _subloadCallback.get(); } - /** Set the number of mip map levels the the texture has been created with, - should only be called within an osg::Texuture::apply() and custom OpenGL texture load.*/ + /** Helper function. Sets the number of mipmap levels created for this + * texture. Should only be called within an osg::Texuture::apply(), or + * during a custom OpenGL texture load. */ void setNumMipmapLevels(unsigned int num) const { _numMipmapLevels=num; } - /** Get the number of mip map levels the the texture has been created with.*/ + /** Gets the number of mipmap levels created. */ unsigned int getNumMipmapLevels() const { return _numMipmapLevels; } - /** Copy pixels into a 2D texture image.As per glCopyTexImage2D. + /** Copies pixels into a 2D texture image, as per glCopyTexImage2D. * Creates an OpenGL texture object from the current OpenGL background - * framebuffer contents at pos \a x, \a y with width \a width and - * height \a height. \a width and \a height must be a power of two. - */ + * framebuffer contents at position \a x, \a y with width \a width and + * height \a height. \a width and \a height must be a power of two. */ void copyTexImage2D(State& state, int x, int y, int width, int height ); - /** Copy a two-dimensional texture subimage. As per glCopyTexSubImage2D. - * Updates portion of an existing OpenGL texture object from the current OpenGL background - * framebuffer contents at pos \a x, \a y with width \a width and - * height \a height. \a width and \a height must be a power of two, - * and writing into the texture with offset \a xoffset and \a yoffset. - */ + /** Copies a two-dimensional texture subimage, as per + * glCopyTexSubImage2D. Updates a portion of an existing OpenGL + * texture object from the current OpenGL background framebuffer + * contents at position \a x, \a y with width \a width and height + * \a height. Loads framebuffer data into the texture using offsets + * \a xoffset and \a yoffset. \a width and \a height must be powers + * of two. */ void copyTexSubImage2D(State& state, int xoffset, int yoffset, int x, int y, int width, int height ); - /** On first apply (unless already compiled), create the minmapped - * texture and bind it, subsequent apply will simple bind to texture.*/ + /** Bind the texture object. If the texture object hasn't already been + * compiled, create the texture mipmap levels. */ virtual void apply(State& state) const; protected : @@ -139,16 +142,16 @@ class SG_EXPORT Texture2D : public Texture virtual void computeInternalFormat() const; - // not ideal that _image is mutable, but its required since - // Image::ensureDimensionsArePowerOfTwo() can only be called - // in a valid OpenGL context, a therefore within an Texture::apply - // which is const... + /** It's not ideal that _image is mutable, but it's required since + * Image::ensureDimensionsArePowerOfTwo() can only be called in a + * valid OpenGL context, and therefore within Texture::apply, which + * is const. */ ref_ptr _image; - // subloaded images can have different texture and image sizes. + /** Subloaded images can have different texture and image sizes. */ mutable GLsizei _textureWidth, _textureHeight; - // number of mip map levels the the texture has been created with, + /** Number of mipmap levels created. */ mutable GLsizei _numMipmapLevels; ref_ptr _subloadCallback; diff --git a/include/osg/Texture3D b/include/osg/Texture3D index 1e2494187..2e1836a61 100644 --- a/include/osg/Texture3D +++ b/include/osg/Texture3D @@ -18,7 +18,9 @@ namespace osg { -/** Texture state class which encapsulates OpenGl 3D texture functionality.*/ +/** Encapsulates OpenGl 2D texture functionality. Doesn't support cube maps, + * so ignore \a face parameters. +*/ class SG_EXPORT Texture3D : public Texture { @@ -26,12 +28,12 @@ class SG_EXPORT Texture3D : public Texture Texture3D(); - /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ + /** Copy constructor using CopyOp to manage deep vs shallow copy. */ Texture3D(const Texture3D& text,const CopyOp& copyop=CopyOp::SHALLOW_COPY); META_StateAttribute(osg, Texture3D,TEXTURE); - /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ + /** Return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs. */ virtual int compare(const StateAttribute& rhs) const; virtual bool getModeUsage(ModeUsage& usage) const @@ -40,13 +42,13 @@ class SG_EXPORT Texture3D : public Texture return true; } - /** Set the texture image. */ + /** Sets the texture image. */ void setImage(Image* image); - /** Get the texture image. */ + /** Gets the texture image. */ Image* getImage() { return _image.get(); } - /** Get the const texture image. */ + /** Gets the const texture image. */ inline const Image* getImage() const { return _image.get(); } inline unsigned int& getModifiedTag(unsigned int contextID) const @@ -55,21 +57,22 @@ class SG_EXPORT Texture3D : public Texture return _modifiedTag[contextID]; } - /** Set the texture image, ignoring face. as there is only one image*/ + /** Sets the texture image, ignoring face. */ virtual void setImage(unsigned int, Image* image) { setImage(image); } - /** Get the texture image, ignoring face value as there is only one image. */ + /** Gets the texture image, ignoring face. */ virtual Image* getImage(unsigned int) { return _image.get(); } - /** Get the const texture image , ignoring face value as there is only one image. */ + /** Gets the const texture image, ignoring face. */ virtual const Image* getImage(unsigned int) const { return _image.get(); } - /** Get the number of images that can be assigned to the Texture. */ + /** Gets the number of images that can be assigned to the Texture. */ virtual unsigned int getNumImages() const { return 1; } - /** Set the texture width and height. If width or height are zero then - * the repsective size value is calculated from the source image sizes. */ + /** Sets the texture width, height, and depth. If width, height, or + * depth are zero, calculate the respective value from the source + * image size. */ inline void setTextureSize(int width, int height, int depth) const { _textureWidth = width; @@ -77,7 +80,7 @@ class SG_EXPORT Texture3D : public Texture _textureDepth = depth; } - /** Get the texture subload width. */ + /** Gets the texture subload width. */ inline void getTextureSize(int& width, int& height, int& depth) const { width = _textureWidth; @@ -100,29 +103,33 @@ class SG_EXPORT Texture3D : public Texture const SubloadCallback* getSubloadCallback() const { return _subloadCallback.get(); } - /** Set the number of mip map levels the the texture has been created with, - should only be called within an osg::Texuture::apply() and custom OpenGL texture load.*/ + /** Helper function. Sets the number of mipmap levels created for this + * texture. Should only be called within an osg::Texuture::apply(), or + * during a custom OpenGL texture load. */ void setNumMipmapLevels(unsigned int num) const { _numMipmapLevels=num; } - /** Get the number of mip map levels the the texture has been created with.*/ + /** Gets the number of mipmap levels created. */ unsigned int getNumMipmapLevels() const { return _numMipmapLevels; } - /** Copy a two-dimensional texture subimage. As per glCopyTexSubImage2D. - * Updates portion of an existing OpenGL texture object from the current OpenGL background - * framebuffer contents at pos \a x, \a y with width \a width and - * height \a height. */ + /** Copies a two-dimensional texture subimage, as per + * glCopyTexSubImage3D. Updates a portion of an existing OpenGL + * texture object from the current OpenGL background framebuffer + * contents at position \a x, \a y with width \a width and height + * \a height. Loads framebuffer data into the texture using offsets + * \a xoffset, \a yoffset, and \a zoffset. \a width and \a height + * must be powers of two. */ void copyTexSubImage3D(State& state, int xoffset, int yoffset, int zoffset, int x, int y, int width, int height); - /** On first apply (unless already compiled), create the minmapped - * texture and bind it, subsequent apply will simple bind to texture.*/ + /** Bind the texture object. If the texture object hasn't already been + * compiled, create the texture mipmap levels. */ virtual void apply(State& state) const; - /** Extensions class which encapsulates the querring of extensions and - * associated function pointers, and provide convinience wrappers to - * check for the extensions or use the associated functions.*/ + /** Encapsulates queries of extension availability, obtains extension + * function pointers, and provides convinience wrappers for + * calling extension functions. */ class SG_EXPORT Extensions : public osg::Referenced { public: @@ -170,17 +177,14 @@ class SG_EXPORT Texture3D : public Texture }; - /** Function to call to get the extension of a specified context. - * If the Exentsion object for that context has not yet been created then - * and the 'createIfNotInitalized' flag been set to false then returns NULL. - * If 'createIfNotInitalized' is true then the Extensions object is - * automatically created. However, in this case the extension object - * only be created with the graphics context associated with ContextID..*/ + /** Encapsulates queries of extension availability, obtains extension + * function pointers, and provides convinience wrappers for + * calling extension functions. */ static Extensions* getExtensions(unsigned int contextID,bool createIfNotInitalized); - /** setExtensions allows users to override the extensions across graphics contexts. - * typically used when you have different extensions supported across graphics pipes - * but need to ensure that they all use the same low common denominator extensions.*/ + /** Overrides Extensions objects across graphics contexts. Typically + * used to ensure the same lowest common denominator of extensions + * on sustems with different graphics pipes. */ static void setExtensions(unsigned int contextID,Extensions* extensions); protected : @@ -191,16 +195,16 @@ class SG_EXPORT Texture3D : public Texture void applyTexImage3D(GLenum target, Image* image, State& state, GLsizei& inwidth, GLsizei& inheight, GLsizei& indepth, GLsizei& numMipmapLevels) const; - // not ideal that _image is mutable, but its required since - // Image::ensureDimensionsArePowerOfTwo() can only be called - // in a valid OpenGL context, a therefore within an Texture::apply - // which is const... + /** It's not ideal that _image is mutable, but it's required since + * Image::ensureDimensionsArePowerOfTwo() can only be called in a + * valid OpenGL context, and therefore within Texture::apply, which + * is const. */ mutable ref_ptr _image; - // subloaded images can have different texture and image sizes. + /** Subloaded images can have different texture and image sizes. */ mutable GLsizei _textureWidth, _textureHeight, _textureDepth; - // number of mip map levels the the texture has been created with, + /** Number of mip map levels the the texture has been created with, */ mutable GLsizei _numMipmapLevels; ref_ptr _subloadCallback;