.TH "SoSFImage" 3 "Tue Dec 26 2023 17:59:22" "Version 4.0.2" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SoSFImage \- The \fBSoSFImage\fP class is used to store pixel images\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBSoSField\fP\&. .SS "Public Types" .in +1c .ti -1c .RI "enum \fBCopyPolicy\fP { \fBCOPY\fP, \fBNO_COPY\fP, \fBNO_COPY_AND_DELETE\fP, \fBNO_COPY_AND_FREE\fP }" .br .in -1c Public Types inherited from \fBSoField\fP .in +1c .ti -1c .RI "enum \fBFieldType\fP { \fBNORMAL_FIELD\fP = 0, \fBEVENTIN_FIELD\fP, \fBEVENTOUT_FIELD\fP, \fBEXPOSED_FIELD\fP }" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBvirtual\fP \fBSoType\fP \fBgetTypeId\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBcopyFrom\fP (\fBconst\fP \fBSoField\fP &\fBfield\fP)" .br .ti -1c .RI "\fBconst\fP \fBSoSFImage\fP & \fBoperator=\fP (\fBconst\fP \fBSoSFImage\fP &\fBfield\fP)" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBisSame\fP (\fBconst\fP \fBSoField\fP &\fBfield\fP) \fBconst\fP" .br .ti -1c .RI "\fBconst\fP \fBunsigned\fP char * \fBgetValue\fP (\fBSbVec2s\fP &size, int &\fBnc\fP) \fBconst\fP" .br .ti -1c .RI "\fBconst\fP \fBSbImage\fP & \fBgetValue\fP () \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetValue\fP (\fBconst\fP \fBSbVec2s\fP &size, \fBconst\fP int \fBnc\fP, \fBconst\fP \fBunsigned\fP char *pixels, CopyPolicy \fBcopypolicy\fP=COPY)" .br .ti -1c .RI "int \fBoperator==\fP (\fBconst\fP \fBSoSFImage\fP &\fBfield\fP) \fBconst\fP" .br .ti -1c .RI "int \fBoperator!=\fP (\fBconst\fP \fBSoSFImage\fP &\fBfield\fP) \fBconst\fP" .br .ti -1c .RI "\fBunsigned\fP char * \fBstartEditing\fP (\fBSbVec2s\fP &size, int &\fBnc\fP)" .br .ti -1c .RI "\fBvoid\fP \fBfinishEditing\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBsetSubValue\fP (\fBconst\fP \fBSbVec2s\fP &\fBdims\fP, \fBconst\fP \fBSbVec2s\fP &offset, \fBunsigned\fP char *pixels)" .br .ti -1c .RI "\fBvoid\fP \fBsetSubValues\fP (\fBconst\fP \fBSbVec2s\fP *\fBdims\fP, \fBconst\fP \fBSbVec2s\fP *\fBoffsets\fP, int num, \fBunsigned\fP char **\fBpixelblocks\fP)" .br .ti -1c .RI "\fBunsigned\fP char * \fBgetSubTexture\fP (int idx, \fBSbVec2s\fP &\fBdims\fP, \fBSbVec2s\fP &offset) \fBconst\fP" .br .ti -1c .RI "SbBool \fBhasSubTextures\fP (int &\fBnumsubtextures\fP)" .br .ti -1c .RI "\fBvoid\fP \fBsetNeverWrite\fP (SbBool \fBflag\fP)" .br .ti -1c .RI "SbBool \fBisNeverWrite\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBhasTransparency\fP (\fBvoid\fP) \fBconst\fP" .br .in -1c Public Member Functions inherited from \fBSoSField\fP .in +1c .ti -1c .RI "\fBvirtual\fP \fB~SoSField\fP ()" .br .in -1c Public Member Functions inherited from \fBSoField\fP .in +1c .ti -1c .RI "\fBvirtual\fP \fB~SoField\fP ()" .br .ti -1c .RI "\fBvoid\fP \fBsetIgnored\fP (SbBool \fBignore\fP)" .br .ti -1c .RI "SbBool \fBisIgnored\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetDefault\fP (SbBool \fBdefaultVal\fP)" .br .ti -1c .RI "SbBool \fBisDefault\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBisOfType\fP (\fBconst\fP \fBSoType\fP type) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBenableConnection\fP (SbBool \fBflag\fP)" .br .ti -1c .RI "SbBool \fBisConnectionEnabled\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBconnectFrom\fP (\fBSoEngineOutput\fP *master, SbBool \fBnotnotify\fP=FALSE, SbBool append=FALSE)" .br .ti -1c .RI "SbBool \fBappendConnection\fP (\fBSoEngineOutput\fP *master, SbBool \fBnotnotify\fP=FALSE)" .br .ti -1c .RI "\fBvoid\fP \fBdisconnect\fP (\fBSoEngineOutput\fP *\fBengineoutput\fP)" .br .ti -1c .RI "SbBool \fBisConnectedFromEngine\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBgetConnectedEngine\fP (\fBSoEngineOutput\fP *&master) \fBconst\fP" .br .ti -1c .RI "SbBool \fBconnectFrom\fP (\fBSoField\fP *master, SbBool \fBnotnotify\fP=FALSE, SbBool append=FALSE)" .br .ti -1c .RI "SbBool \fBappendConnection\fP (\fBSoField\fP *master, SbBool \fBnotnotify\fP=FALSE)" .br .ti -1c .RI "\fBvoid\fP \fBdisconnect\fP (\fBSoField\fP *\fBfield\fP)" .br .ti -1c .RI "SbBool \fBisConnectedFromField\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBgetConnectedField\fP (\fBSoField\fP *&master) \fBconst\fP" .br .ti -1c .RI "int \fBgetNumConnections\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "int \fBgetForwardConnections\fP (\fBSoFieldList\fP &\fBslavelist\fP) \fBconst\fP" .br .ti -1c .RI "int \fBgetConnections\fP (\fBSoFieldList\fP &\fBmasterlist\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBdisconnect\fP (\fBvoid\fP)" .br .ti -1c .RI "SbBool \fBisConnected\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetContainer\fP (\fBSoFieldContainer\fP *\fBcont\fP)" .br .ti -1c .RI "\fBSoFieldContainer\fP * \fBgetContainer\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBset\fP (\fBconst\fP char *\fBvaluestring\fP)" .br .ti -1c .RI "\fBvoid\fP \fBget\fP (\fBSbString\fP &\fBvaluestring\fP)" .br .ti -1c .RI "SbBool \fBshouldWrite\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBtouch\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBstartNotify\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBnotify\fP (\fBSoNotList\fP *\fBnlist\fP)" .br .ti -1c .RI "SbBool \fBenableNotify\fP (SbBool on)" .br .ti -1c .RI "SbBool \fBisNotifyEnabled\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBaddAuditor\fP (\fBvoid\fP *f, \fBSoNotRec::Type\fP type)" .br .ti -1c .RI "\fBvoid\fP \fBremoveAuditor\fP (\fBvoid\fP *f, \fBSoNotRec::Type\fP type)" .br .ti -1c .RI "int \fBoperator==\fP (\fBconst\fP \fBSoField\fP &f) \fBconst\fP" .br .ti -1c .RI "int \fBoperator!=\fP (\fBconst\fP \fBSoField\fP &f) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBconnectionStatusChanged\fP (int \fBnumconnections\fP)" .br .ti -1c .RI "SbBool \fBisReadOnly\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBfixCopy\fP (SbBool \fBcopyconnections\fP)" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBreferencesCopy\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBcopyConnection\fP (\fBconst\fP \fBSoField\fP *fromfield)" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBread\fP (\fBSoInput\fP *input, \fBconst\fP \fBSbName\fP &name)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBwrite\fP (\fBSoOutput\fP *\fBout\fP, \fBconst\fP \fBSbName\fP &name) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBcountWriteRefs\fP (\fBSoOutput\fP *\fBout\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetFieldType\fP (int type)" .br .ti -1c .RI "int \fBgetFieldType\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBgetDirty\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetDirty\fP (SbBool dirty)" .br .ti -1c .RI "\fBvoid\fP \fBevaluate\fP (\fBvoid\fP) \fBconst\fP" .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "\fBstatic\fP \fBvoid\fP * \fBcreateInstance\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoType\fP \fBgetClassTypeId\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClass\fP (\fBvoid\fP)" .br .in -1c Static Public Member Functions inherited from \fBSoSField\fP .in +1c .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClass\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoType\fP \fBgetClassTypeId\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBatexit_cleanup\fP (\fBvoid\fP)" .br .in -1c Static Public Member Functions inherited from \fBSoField\fP .in +1c .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClass\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClasses\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBcleanupClass\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoType\fP \fBgetClassTypeId\fP (\fBvoid\fP)" .br .in -1c .SS "Additional Inherited Members" Protected Member Functions inherited from \fBSoSField\fP .in +1c .ti -1c .RI "\fBSoSField\fP (\fBvoid\fP)" .br .in -1c Protected Member Functions inherited from \fBSoField\fP .in +1c .ti -1c .RI "\fBSoField\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBvalueChanged\fP (SbBool \fBresetdefault\fP=TRUE)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBevaluateConnection\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBreadConnection\fP (\fBSoInput\fP *\fBin\fP)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBwriteConnection\fP (\fBSoOutput\fP *\fBout\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBisDestructing\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBSoNotRec\fP \fBcreateNotRec\fP (\fBSoBase\fP *\fBcont\fP)" .br .in -1c .SH "Detailed Description" .PP The \fBSoSFImage\fP class is used to store pixel images\&. The \fBSoSFImage\fP class provides storage for inline 2D image maps\&. Images in Coin are mainly used for texture mapping support\&. .PP \fBSoSFImage\fP instances can be exported and imported as any other field class in Coin\&. .PP The components of an \fBSoSFImage\fP is: its image dimensions (width and height), the number of bytes used for describing each pixel (number of components) and an associated pixel buffer\&. The size of the pixel buffer will be width*height*components\&. .PP For texture maps, the components / bytes-per-pixel setting translates as follows: use 1 for a grayscale imagemap, 2 for grayscale + opacity (i\&.e\&. alpha value), 3 for RGB (1 byte each for red, green and blue) and 4 components means 3 bytes for RGB + 1 byte opacity value (aka RGBA)\&. .PP This field is serializable into the Inventor / Coin file format in the following manner: .PP .PP .nf FIELDNAME X Y C 0xRRGGBBAA 0xRRGGBBAA \&.\&.\&. .fi .PP .PP 'X' and 'Y' are the image dimensions along the given axes, 'C' is the number of components in the image\&. The number of 0xRRGGBBAA pixel color specifications needs to equal the exact number of pixels, which of course is given by X*Y\&. Each part of the pixel color value is in the range 0x00 to 0xff (hexadecimal, 0 to 255 decimal)\&. .PP For 3-component images, the pixel-format is 0xXXRRGGBB, where the byte in the pixel color value marked as 'XX' is ignored and can be left out\&. .PP For 2-component images, the pixel-format is 0xXXXXGGAA, where the bytes in the pixel color values marked as 'XX' are ignored and can be left out\&. 'GG' is the part which gives a grayscale value and 'AA' is for opacity\&. .PP For 1-component images, the pixel-format is 0xXXXXXXGG, where the bytes in the pixel color values marked as 'XX' are ignored and can be left out\&. .PP The pixels are read as being ordered in rows along X (width) and columns along Y (height, bottom to top)\&. .PP Here's a simple example of the file format serialization, for a 2x2 RGB-image inside an \fBSoTexture2\fP node, as mapped onto an \fBSoCube\fP: .PP .PP .nf Complexity { textureQuality 0\&.1 } # set low to avoid smoothing Texture2 { image 2 2 4 0xffffffff 0x00ff0088 # white semi\-transparent green 0xff0000ff 0xffff00ff # red yellow } Cube { } .fi .PP .PP The mini-scene graph above results in the following mapping on the cube: .br .PP .PP The cube has only been \fIslightly\fP rotated, so as you can see from the snapshot, the Y-rows are mapped from bottom to top, while the X-column pixels are mapped onto the cube from left to right\&. .PP \fBSee also\fP .RS 4 \fBSoTexture2\fP, \fBSoSFImage3\fP .RE .PP .SH "Member Function Documentation" .PP .SS "\fBvoid\fP * SoSFImage::createInstance (\fBvoid\fP)\fC [static]\fP" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br Creates a new instance of the class type corresponding to the \fBSoType\fP object\&. .br .SS "\fBSoType\fP SoSFImage::getClassTypeId (\fBvoid\fP)\fC [static]\fP" This static method returns the \fBSoType\fP object associated with objects of this class\&. .br .SS "\fBSoType\fP SoSFImage::getTypeId (\fBvoid\fP) const\fC [virtual]\fP" Returns the type identification of an object derived from a class inheriting \fBSoField\fP\&. This is used for runtime type checking and 'downward' casting\&. .br .PP Implements \fBSoField\fP\&. .SS "\fBvoid\fP SoSFImage::copyFrom (\fBconst\fP \fBSoField\fP & f)\fC [virtual]\fP" Copy value(s) from \fIf\fP into this field\&. \fIf\fP must be of the same type as this field\&. .PP Implements \fBSoField\fP\&. .SS "SbBool SoSFImage::isSame (\fBconst\fP \fBSoField\fP & f) const\fC [virtual]\fP" Check for equal type and value(s)\&. .PP Implements \fBSoField\fP\&. .SS "\fBvoid\fP SoSFImage::initClass (\fBvoid\fP)\fC [static]\fP" Internal method called upon initialization of the library (from \fBSoDB::init()\fP) to set up the type system\&. .SS "\fBconst\fP \fBunsigned\fP char * SoSFImage::getValue (\fBSbVec2s\fP & size, int & nc) const" Return pixel buffer, set \fIsize\fP to contain the image dimensions and \fInc\fP to the number of components in the image\&. .SS "\fBconst\fP \fBSbImage\fP & SoSFImage::getValue () const" .PP \fBReturn values\fP .RS 4 \fI\fBSbImage\fP\fP contained by this \fBSoSFImage\fP .RE .PP .SS "\fBvoid\fP SoSFImage::setValue (\fBconst\fP \fBSbVec2s\fP & size, \fBconst\fP int nc, \fBconst\fP \fBunsigned\fP char * pixels, SoSFImage::CopyPolicy copypolicy = \fCCOPY\fP)" Initialize this field to \fIsize\fP and \fInc\fP\&. .PP If \fIpixels\fP is not \fCNULL\fP, the image data is copied from \fIpixels\fP into this field\&. If \fIpixels\fP is \fCNULL\fP, the image data is cleared by setting all bytes to 0 (note that the behavior on passing a \fCNULL\fP pointer is specific for Coin, Open Inventor will crash if you try it)\&. .PP The image dimensions is given by the \fIsize\fP argument, and the \fInc\fP argument specifies the number of bytes-pr-pixel\&. A 24-bit RGB image would for instance have an \fInc\fP equal to 3\&. .PP The \fIcopypolicy\fP argument makes it possible to share image data with \fBSoSFImage\fP without the data being copied (thereby using less memory resources)\&. The default is to copy image data from the \fIpixels\fP source into an internal copy\&. .PP \fIImportant\fP \fInote:\fP if you call this with \fIcopypolicy\fP as either \fCNO_COPY_AND_DELETE\fP or \fCNO_COPY_AND_FREE\fP, and your application is running on Microsoft Windows, be aware that you will get mysterious crashes if your application is not using the same C library runtime as the Coin library\&. .PP The cause of this is that a memory block would then be allocated by the application on the memory heap of one C library runtime (say, for instance \fC\fBMSVCRT\&.LIB\fP\fP), but attempted deallocated in the memory heap of another C library runtime (e\&.g\&. \fC\fBMSVCRTD\&.LIB\fP\fP), which typically leads to hard-to-debug crashes\&. .PP \fBSince\fP .RS 4 The CopyPolicy argument was added in Coin \fB2\&.0\fP\&. .PP CopyPolicy was added to TGS Inventor \fB3\&.0\fP\&. .RE .PP .SS "int SoSFImage::operator== (\fBconst\fP \fBSoSFImage\fP & field) const" Compare image of \fIfield\fP with the image in this field and return \fCTRUE\fP if they are equal\&. .SS "int SoSFImage::operator!= (\fBconst\fP \fBSoSFImage\fP & field) const\fC [inline]\fP" Compare image of \fIfield\fP with the image in this field and return \fCFALSE\fP if they are equal\&. .SS "\fBunsigned\fP char * SoSFImage::startEditing (\fBSbVec2s\fP & size, int & nc)" Return pixel buffer\&. Return the image size and components in \fIsize\fP and \fInc\fP\&. .PP You cannot use this method to set a new image size\&. Use \fBsetValue()\fP to change the size of the image buffer\&. .PP The field's container will not be notified about the changes until you call \fBfinishEditing()\fP\&. .SS "\fBvoid\fP SoSFImage::finishEditing (\fBvoid\fP)" Notify the field's auditors that the image data have been modified\&. .SS "\fBvoid\fP SoSFImage::setSubValue (\fBconst\fP \fBSbVec2s\fP & dims, \fBconst\fP \fBSbVec2s\fP & offset, \fBunsigned\fP char * pixels)" Not yet implemented for Coin\&. Get in touch if you need this method\&. .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor \fB3\&.0\fP .RE .PP .SS "\fBvoid\fP SoSFImage::setSubValues (\fBconst\fP \fBSbVec2s\fP * dims, \fBconst\fP \fBSbVec2s\fP * offsets, int num, \fBunsigned\fP char ** pixelblocks)" Not yet implemented for Coin\&. Get in touch if you need this method\&. .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor \fB3\&.0\fP .RE .PP .SS "\fBunsigned\fP char * SoSFImage::getSubTexture (int idx, \fBSbVec2s\fP & dims, \fBSbVec2s\fP & offset) const" Not yet implemented for Coin\&. Get in touch if you need this method\&. .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor \fB3\&.0\fP .RE .PP .SS "SbBool SoSFImage::hasSubTextures (int & numsubtextures)" Returns whether or not sub textures was set up for this field\&. .PP If \fCTRUE\fP is returned, the \fInumsubtextures\fP argument will be set to the number of sub textures in this image\&. This number can be used for iterating over all textures with the SoSFImage::getSubTextures() method\&. .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor \fB3\&.0\fP .RE .PP .SS "\fBvoid\fP SoSFImage::setNeverWrite (SbBool flag)" Set this flag to true to avoid writing out the texture to file\&. This can save a lot on file size\&. .PP Default value is \fCFALSE\fP (i\&.e\&. write texture data to file\&.) .PP (Note: yet unimplemented for Coin\&.) .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor ?\&.? .RE .PP .SS "SbBool SoSFImage::isNeverWrite (\fBvoid\fP) const" Returns value of 'never write texture data' flag\&. .PP \fBSee also\fP .RS 4 \fBSoSFImage::setNeverWrite()\fP .RE .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor ?\&.? .RE .PP .SS "SbBool SoSFImage::hasTransparency (\fBvoid\fP) const" Returns \fCTRUE\fP if at least one pixel of the image in this field is not completely opaque, otherwise \fCFALSE\fP\&. .PP \fBSince\fP .RS 4 Coin \fB2\&.0\fP .PP TGS Inventor ?\&.? .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.