From cc471b1103afda5987021e44177d608972630129 Mon Sep 17 00:00:00 2001 From: Robert Osfield Date: Wed, 15 Sep 2010 12:00:12 +0000 Subject: [PATCH] From Magnus Kessler, "Attached are a number of files where I have tried to fix up some of the documentation. I have accumulated them over some time, but rebased onto the subversion trunk." --- CMakeLists.txt | 2 +- examples/osggeometry/osggeometry.cpp | 28 +++++++++---------- examples/osgoccluder/osgoccluder.cpp | 14 +++++----- include/osg/Camera | 16 +++++++---- include/osg/CameraView | 4 +-- include/osg/GraphicsContext | 6 ++-- include/osg/OccluderNode | 9 +++--- include/osg/Referenced | 12 ++++---- include/osg/observer_ptr | 4 +-- include/osgDB/ReaderWriter | 42 ++++++++++++++-------------- include/osgViewer/CompositeViewer | 30 ++++++++++---------- include/osgWidget/Browser | 6 ++-- 12 files changed, 88 insertions(+), 85 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 96c8878b4..49f1e3eaa 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -281,7 +281,7 @@ ENDIF(WIN32) #luigi#ENDIF(UNIX) ######################################################################################################## -OPTION(OSG_NOTIFY_DISABLED "Set to ON to build OpenSceneGraph with the noitfy() disabled." OFF) +OPTION(OSG_NOTIFY_DISABLED "Set to ON to build OpenSceneGraph with the notify() disabled." OFF) OPTION(OSG_USE_FLOAT_MATRIX "Set to ON to build OpenSceneGraph with float Matrix instead of double." OFF) MARK_AS_ADVANCED(OSG_USE_FLOAT_MATRIX) diff --git a/examples/osggeometry/osggeometry.cpp b/examples/osggeometry/osggeometry.cpp index cb881f6a8..a0c270d77 100644 --- a/examples/osggeometry/osggeometry.cpp +++ b/examples/osggeometry/osggeometry.cpp @@ -37,12 +37,12 @@ #include -// This demos uses the illustrates how to creates the various different types of geometry that -// the osg::Geometry class can represent. This demos uses the OpenGL red books diagram of different +// This demo illustrates how to create the various different types of geometry that +// the osg::Geometry class can represent. This demo uses the OpenGL red book diagram of different // OpenGL Primitives as a template for all the equivalent OpenSceneGraph Primitives. The OpenSceneGraph -// wraps OpenGL very thinly so uses all the same enum and naming conventions. The coordinate data is also +// wraps OpenGL very thinly and therefore uses all the same enum and naming conventions. The coordinate data is also // wrapped around OpenGL's vertex arrays and draw arrays/elements calls. Familiarity with -// OpenGL will help understand the the osg::Geometry class which encapsulate all this, or if you +// OpenGL will help you understand the osg::Geometry class which encapsulate all this, or if you // havn't learned OpenGL yet, learning osg::Geometry will help you understand how OpenGL // works! @@ -84,9 +84,9 @@ osg::Node* createScene() // create the Geode (Geometry Node) to contain all our osg::Geometry objects. osg::Geode* geode = new osg::Geode(); - // follows are separate blocks for creating POINTS, LINES, LINE_STRIP, LINE_LOOP, POLYGON, QUADS, - // QUAD_STRIP, TRIANGLES, TRIANGLE_STRIP and TRIANGLE_FAN primitives. A image of these primitives - // are provided in the distribution : OpenSceneGraph-Data/Images/primitives.gif. + // following are separate blocks for creating POINTS, LINES, LINE_STRIP, LINE_LOOP, POLYGON, QUADS, + // QUAD_STRIP, TRIANGLES, TRIANGLE_STRIP and TRIANGLE_FAN primitives. An image of these primitives + // is provided in the distribution: OpenSceneGraph-Data/Images/primitives.gif. // create POINTS @@ -297,20 +297,20 @@ osg::Node* createScene() // Note on vertex ordering. - // While the OpenGL diagram should vertices specified in a clockwise direction - // in reality you need to specify coords for polygons into a anticlockwise direction - // for their front face to be pointing towards your, get this wrong and you could + // According to the OpenGL diagram vertices should be specified in a clockwise direction. + // In reality you need to specify coords for polygons in a anticlockwise direction + // for their front face to be pointing towards you; get this wrong and you could // find back face culling removing the wrong faces of your models. The OpenGL diagram - // is just plain wrong, but its nice diagram so we'll keep it for now! + // is just plain wrong, but it's a nice diagram so we'll keep it for now! // create POLYGON { // create Geometry object to store all the vertices and lines primitive. osg::Geometry* polyGeom = new osg::Geometry(); - // this time we'll a C arrays to initialize the vertices. + // this time we'll use C arrays to initialize the vertices. // note, anticlockwise ordering. - // note II, OpenGL polygons must be convex plan polygons, otherwise + // note II, OpenGL polygons must be convex, planar polygons, otherwise // undefined results will occur. If you have concave polygons or ones // that cross over themselves then use the osgUtil::Tessellator to fix // the polygons into a set of valid polygons. @@ -529,7 +529,7 @@ osg::Node* createScene() } -// define a node callback to animation a transform as a cycle along the y axis, between 0 and 2.0. +// define a node callback to animate a transform as a cycle along the y axis, between 0 and 2.0. class MyTransformCallback : public osg::NodeCallback { diff --git a/examples/osgoccluder/osgoccluder.cpp b/examples/osgoccluder/osgoccluder.cpp index 6c1c89af9..f9832b033 100644 --- a/examples/osgoccluder/osgoccluder.cpp +++ b/examples/osgoccluder/osgoccluder.cpp @@ -164,10 +164,10 @@ void OccluderEventHandler::endOccluder() osg::Node* createOccluder(const osg::Vec3& v1,const osg::Vec3& v2,const osg::Vec3& v3,const osg::Vec3& v4,float holeRatio=-1.0f) { - // create and occluder which will site along side the loadmodel model. + // create an occluder which will sit alongside the loaded model. osg::OccluderNode* occluderNode = new osg::OccluderNode; - // create the convex planer occluder + // create the convex planar occluder osg::ConvexPlanarOccluder* cpo = new osg::ConvexPlanarOccluder; // attach it to the occluder node. @@ -181,7 +181,7 @@ osg::Node* createOccluder(const osg::Vec3& v1,const osg::Vec3& v2,const osg::Vec occluder.add(v3); occluder.add(v4); - // create a whole at the center of the occluder if needed. + // create a hole at the center of the occluder if needed. if (holeRatio>0.0f) { // create hole. @@ -228,7 +228,7 @@ osg::Node* createOccluder(const osg::Vec3& v1,const osg::Vec3& v2,const osg::Vec // add the occluder geode as a child of the occluder, // as the occluder can't self occlude its subgraph the - // geode will never be occluder by this occluder. + // geode will never be occluded by this occluder. occluderNode->addChild(geode); return occluderNode; @@ -304,7 +304,7 @@ int main( int argc, char **argv ) viewer.addEventHandler(new OccluderEventHandler(&viewer)); } - // if user request help write it out to cout. + // if user requests help write it out to cout. if (arguments.read("-h") || arguments.read("--help")) { arguments.getApplicationUsage()->write(std::cout); @@ -314,12 +314,12 @@ int main( int argc, char **argv ) // load the nodes from the commandline arguments. osg::Node* loadedmodel = osgDB::readNodeFiles(arguments); - // if not loaded assume no arguments passed in, try use default mode instead. + // if not loaded assume no arguments passed in, try using default mode instead. if (!loadedmodel) loadedmodel = osgDB::readNodeFile("glider.osg"); if (!loadedmodel) { - osg::notify(osg::NOTICE)<<"Please sepecify and model filename on the command line."< robustly in multi-threaded applications it is recommend to access the pointer via * the lock() method that passes back a ref_ptr<> that safely takes a reference to the object to prevent deletion * during usage of the object. In certain conditions it may be safe to use the pointer directly without using lock(), @@ -32,7 +32,7 @@ namespace osg { * 2) The data strucutre is guarenteed by high level management of data strucutures and threads which avoid * possible situations where the observer_ptr<>'s object may be deleted by one thread whilst being accessed * by another. - * If you are in any doubt about whether it is safe to access the object safe then use + * If you are in any doubt about whether it is safe to access the object safe then use the * ref_ptr<> observer_ptr<>.lock() combination. */ template class observer_ptr diff --git a/include/osgDB/ReaderWriter b/include/osgDB/ReaderWriter index 41f8eb390..43b3f8d4b 100644 --- a/include/osgDB/ReaderWriter +++ b/include/osgDB/ReaderWriter @@ -28,13 +28,13 @@ namespace osgDB { class Archive; -/** list of directories to search through which searching for files. */ +/** List of directories to search through which searching for files. */ typedef std::deque FilePathList; // forward declare class Options; -/** pure virtual base class for reading and writing of non native formats. */ +/** Pure virtual base class for reading and writing of non native formats. */ class OSGDB_EXPORT ReaderWriter : public osg::Object { public: @@ -53,19 +53,19 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object typedef std::map FormatDescriptionMap; typedef std::list FeatureList; - /** return which protocols are supported by ReaderWriter. */ + /** Return which protocols are supported by ReaderWriter. */ virtual const FormatDescriptionMap& supportedProtocols() const { return _supportedProtocols; } - /** return which list of file extensions supported by ReaderWriter. */ + /** Return which list of file extensions supported by ReaderWriter. */ virtual const FormatDescriptionMap& supportedExtensions() const { return _supportedExtensions; } - /** return which list of file extensions supported by ReaderWriter. */ + /** Return which list of file extensions supported by ReaderWriter. */ virtual const FormatDescriptionMap& supportedOptions() const { return _supportedOptions; } - /** return true if ReaderWriter accepts specified file extension.*/ + /** Return true if ReaderWriter accepts specified file extension.*/ virtual bool acceptsExtension(const std::string& /*extension*/) const; - /// bit mask for setting up which feature types are available for read and/or write + /// Bit mask for setting up which feature types are available for read and/or write enum Features { FEATURE_NONE = 0, @@ -90,10 +90,10 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object FEATURE_WRITE_NODE | FEATURE_WRITE_SHADER }; - /** return available features*/ + /** Return available features*/ virtual Features supportedFeatures() const; - /** return feature as string */ + /** Return feature as string */ static FeatureList featureAsString(Features feature); @@ -104,14 +104,14 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object enum ReadStatus { - NOT_IMPLEMENTED, //!< raad*() method not implemented in concreate ReaderWriter. + NOT_IMPLEMENTED, //!< read*() method not implemented in concrete ReaderWriter. FILE_NOT_HANDLED, //!< File is not appropriate for this file reader, due to some incompatibility, but *not* a read error. FILE_NOT_FOUND, //!< File could not be found or could not be read. FILE_LOADED, //!< File successfully found, loaded, and converted into osg. FILE_LOADED_FROM_CACHE, //!< File found in cache and returned. ERROR_IN_READING_FILE, //!< File found, loaded, but an error was encountered during processing. - FILE_REQUESTED, //!< Asyncronous file read has been requested, but returning immediatiely, keep polling plugin till file read has been completed. - INSUFFICIENT_MEMORY_TO_LOAD //!< File found but not loaded because estimated memory usage is not enought + FILE_REQUESTED, //!< Asynchronous file read has been requested, but returning immediately, keep polling plugin until file read has been completed. + INSUFFICIENT_MEMORY_TO_LOAD //!< File found but not loaded because estimated required memory surpasses available memory. }; ReadResult(ReadStatus status=FILE_NOT_HANDLED):_status(status) {} @@ -167,7 +167,7 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object enum WriteStatus { - NOT_IMPLEMENTED, //!< write*() method not implemented in concreate ReaderWriter. + NOT_IMPLEMENTED, //!< write*() method not implemented in concrete ReaderWriter. FILE_NOT_HANDLED, FILE_SAVED, ERROR_IN_WRITING_FILE @@ -202,14 +202,14 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object typedef osgDB::Options Options; - /** determine if a file exists, normally the default implementation will be approrpiate for local file access - * but with plugins like the libcurl based on it will return true if the file is accessible a server.*/ + /** Determine if a file exists, normally the default implementation will be appropiate for local file access + * but with plugins like the libcurl based one it will return true if the file is accessible at the server. */ virtual bool fileExists(const std::string& filename, const Options* options) const; - /** open an archive for reading, writing, or to create an empty archive for writing to.*/ + /** Open an archive for reading, writing, or to create an empty archive for writing to.*/ virtual ReadResult openArchive(const std::string& /*fileName*/,ArchiveStatus, unsigned int =4096, const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); } - /** open an archive for reading.*/ + /** Open an archive for reading.*/ virtual ReadResult openArchive(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); } virtual ReadResult readObject(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); } @@ -238,15 +238,15 @@ class OSGDB_EXPORT ReaderWriter : public osg::Object /** Specify fmt string as a supported protocol. * Please note, this method should usually only be used internally by subclasses of ReaderWriter, Only in special cases - * will a ReaderWriter implementation be able to handle a protocol format that is wasn't original designed for. - * To know whether it's safe to inject a new protocol format to an existing ReaderWriter you will need to review + * will a ReaderWriter implementation be able to handle a protocol format that it wasn't originally designed for. + * To know whether it's safe to inject a new protocol format into an existing ReaderWriter you will need to review * the source code and dependencies of that ReaderWriter. */ void supportsProtocol(const std::string& fmt, const std::string& description); /** Specify ext string as a supported file extension. * Please note, this method should usually only be used internally by subclasses of ReaderWriter. Only in special cases - * will a ReaderWriter implementation be able to handle a file extension that is wasn't original designed for. - * To know whether it's safe to inject a new file extension to an existing ReaderWriter you will need to review the + * will a ReaderWriter implementation be able to handle a file extension that it wasn't originally designed for. + * To know whether it's safe to inject a new file extension into an existing ReaderWriter you will need to review the * the source code and dependencies of that ReaderWriter. */ void supportsExtension(const std::string& ext, const std::string& description); diff --git a/include/osgViewer/CompositeViewer b/include/osgViewer/CompositeViewer index c0e50af4d..2f0978ca7 100644 --- a/include/osgViewer/CompositeViewer +++ b/include/osgViewer/CompositeViewer @@ -21,7 +21,7 @@ namespace osgViewer { -/** CompsiteViewer holds a or more views to a one more scenes.*/ +/** CompositeViewer holds one or more views to one or more scenes.*/ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase { public: @@ -31,12 +31,12 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase CompositeViewer(const CompositeViewer&,const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY); CompositeViewer(osg::ArgumentParser& arguments); - + META_Object(osgViewer,CompositeViewer); virtual ~CompositeViewer(); - /** read the viewer configuration from a configuration file.*/ + /** Read the viewer configuration from a configuration file.*/ bool readConfiguration(const std::string& filename); @@ -52,17 +52,17 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase void addView(osgViewer::View* view); void removeView(osgViewer::View* view); - + osgViewer::View* getView(unsigned i) { return _views[i].get(); } const osgViewer::View* getView(unsigned i) const { return _views[i].get(); } - + unsigned int getNumViews() const { return _views.size(); } - - /** Get whether at least of one of this viewers windows are realized.*/ + + /** Get whether at least of one of this viewer's windows are realized.*/ virtual bool isRealized() const; - /** set up windows and associated threads.*/ + /** Set up windows and associated threads.*/ virtual void realize(); virtual void setStartTick(osg::Timer_t tick); @@ -84,7 +84,7 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase */ virtual int run(); - /** check to see if the new frame is required, called by run(..) when FrameScheme is set to ON_DEMAND.*/ + /** Check to see if the new frame is required, called by run() when FrameScheme is set to ON_DEMAND.*/ virtual bool checkNeedToDoFrame(); virtual void advance(double simulationTime=USE_REFERENCE_TIME); @@ -100,9 +100,9 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase osgViewer::View* getViewWithFocus() { return _viewWithFocus.get(); } const osgViewer::View* getViewWithFocus() const { return _viewWithFocus.get(); } - + virtual void getCameras(Cameras& cameras, bool onlyActive=true); - + virtual void getContexts(Contexts& contexts, bool onlyValid=true); virtual void getAllThreads(Threads& threads, bool onlyActive=true); @@ -122,12 +122,12 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase void constructorInit(); virtual void viewerInit(); - + typedef std::vector< osg::ref_ptr > RefViews; RefViews _views; - + bool _firstFrame; - + osg::ref_ptr _stats; osg::Timer_t _startTick; @@ -135,7 +135,7 @@ class OSGVIEWER_EXPORT CompositeViewer : public ViewerBase osg::observer_ptr _cameraWithFocus; osg::observer_ptr _viewWithFocus; - + }; diff --git a/include/osgWidget/Browser b/include/osgWidget/Browser index d70263923..7f747db58 100644 --- a/include/osgWidget/Browser +++ b/include/osgWidget/Browser @@ -48,8 +48,8 @@ class OSGWIDGET_EXPORT BrowserManager : public osg::Object }; -/** Pure virtual base class for that provides the browser inteface for integration with 3rd party implementations. - * Implementation of BrowserImage are provide via the gecko plugin.*/ +/** Pure virtual base class that provides the browser interface for integration with 3rd party implementations. + * Implementations of BrowserImage are provided via the gecko plugin.*/ class BrowserImage : public osg::Image { public: @@ -65,7 +65,7 @@ class BrowserImage : public osg::Image }; -/** Convinience class that provides a interactive quad that can be placed directly in the scene.*/ +/** Convenience class that provides an interactive quad that can be placed directly into the scene.*/ class OSGWIDGET_EXPORT Browser : public osg::Geode { public: