快速入门：3D
A 3D scene is represented as a BaseDocument . A BaseDocument can store objects, materials, takes etc. Cinema 4D can handle multiple documents at once. The document display in the viewport is the active document that can be accessed with GetActiveDocument() . This active document must only be modified in the context of user interaction from the main thread. It must not be edited from within the execution pipeline or from a thread that is not the main thread.
After the active document has been edited, one must call EventAdd() to inform Cinema 4D that something has changed.
另请参阅
// This example creates a new BaseDocument and inserts it // into the application as the currently active document.// create a new document BaseDocument * const newDoc = BaseDocument::Alloc (); if (newDoc == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// insert document into list of documents InsertBaseDocument (newDoc); // make document the active document SetActiveDocument (newDoc);
// set name newDoc-> SetDocumentName ( "new_document.c4d" );
// update Cinema 4D EventAdd ();
BaseObject is the base class of all scene objects. Such scene objects can be polygon objects or splines but also generators, deformers, camera objects or lights.
To create a new object one must know the object type's ID. E.g. the ID for a "Cube" is Ocube . A newly created object can simply be inserted into a BaseDocument that will take ownership.
另请参阅 Scene Elements Overview .
// This example creates a new "Cube" object and // inserts it into the given BaseDocument.// create a new cube object BaseObject * const cube = BaseObject::Alloc ( Ocube ); if (cube == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// insert object into the BaseDocument doc->InsertObject(cube, nullptr , nullptr );
The BaseObject class is based on C4DAtom . This means that parameters of objects can be accessed using C4DAtom::SetParameter() and C4DAtom::GetParameter() .
For each element type, there is typically a header file that includes the parameter IDs. E.g. for the Ocube object type there is the ocube.h header file.
Different objects are based on fundamental base classes. Ocube is based on Obase so it inherits the base class' parameters which are defined in the corresponding header file (e.g. obase.h ).
见 C4DAtom Manual .
// This example changes the name and the size of the given object. // The ID PRIM_CUBE_LEN is defined in ocube.h// set new object name cube-> SetName ( "This is a new Cube." _s);
// set size const 向量 size { 500, 500, 500 }; const DescID sizeID { PRIM_CUBE_LEN }; cube-> SetParameter (sizeID, size, DESCFLAGS_SET::NONE );
Materials and shaders can be created like objects. Materials must be inserted into the host BaseDocument . A new shader instance must be inserted into a host object. This is typically the material using the shader. BaseMaterial is the base class of all materials. 材质 is the class representing the standard Cinema 4D 材质。
见 Materials and Shaders Overview .
// This example creates a new material and a new shader for that material.// create a new material 材质 * const material = Material::Alloc (); if (material == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// insert material into the BaseDocument doc->InsertMaterial(material);
// create a new shader BaseShader * const noiseShader = BaseShader::Alloc ( Xnoise ); if (noiseShader == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// insert shader into the material material-> InsertShader (noiseShader);
// use shader in the "Color" channel const DescID shaderParameterID { MATERIAL_COLOR_SHADER }; material-> SetParameter (shaderParameterID, noiseShader, DESCFLAGS_SET::NONE );
Tags are used to add arbitrary data or additional functionality to given BaseObject . Tags that store information are e.g. NormalTag or UVWTag . A TextureTag is used to assign a material to a BaseObject .
见 BaseTag and VariableTag Manual and TextureTag Manual .
// This example creates a new TextureTag and assigns it to the given object.// create texture tag BaseTag * const textureTag = BaseTag::Alloc ( Ttexture ); if (textureTag == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// assing tag to object cube-> InsertTag (textureTag);
// assing material const DescID materialParameterID { TEXTURETAG_MATERIAL }; textureTag-> SetParameter (materialParameterID, material, DESCFLAGS_SET::NONE );
// set projection const DescID projectionParameterID { TEXTURETAG_PROJECTION }; textureTag-> SetParameter (projectionParameterID, TEXTURETAG_PROJECTION_UVW , DESCFLAGS_SET::NONE );
There are many different ways to access the objects, materials or tags that are stored in a BaseDocument . The user can select objects, materials and tags. The BaseDocument class gives access to these "active" elements. Additionally it is also possible to search for objects by name.
The objects of a scene are organized in a tree. For iterating such a tree see Navigation in Lists and Trees .
// This example accesses the currently active object // and loops over the object's tags. It also loops over // the materials in the scene.// get the active object BaseObject * const activeObject = doc->GetActiveObject(); if (activeObject != nullptr ) { // print the object name const String name = activeObject-> GetName (); ApplicationOutput ( "Active Object: " + name);
// print the name of all tags BaseTag * tag = activeObject-> GetFirstTag (); while (tag != nullptr ) { const String tagName = tag-> GetName (); ApplicationOutput ( "Tag: " + tagName); tag = tag-> GetNext (); } }
// print the name of all materials BaseMaterial * material = doc->GetFirstMaterial(); while (material != nullptr ) { const String materialName = material-> GetName (); ApplicationOutput ( "Material: " + materialName); material = material-> GetNext (); }
A PolygonObject stores point and polygon data. Such a PolygonObject is created and inserted into the BaseDocument like any other object.
// This example creates a new polygon object.// define point and polygon count const Int32 pointCnt = 4; const Int32 polyCnt = 1;
// create polygon object PolygonObject * const polygonObject = PolygonObject::Alloc (pointCnt, polyCnt); if (polygonObject == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );
// insert object into the document doc->InsertObject(polygonObject, nullptr , nullptr );
// accees point and polygon data 向量 * const points = polygonObject-> GetPointW (); CPolygon * const polygons = polygonObject-> GetPolygonW (); const Bool pointsReady = points != nullptr ; const Bool polygonsReady = polygons != nullptr ; if (pointsReady && polygonsReady) { // set points points[0] = 向量 (0, 0, 0); points[1] = 向量 (0, 0, 100); points[2] = 向量 (100, 0, 100); points[3] = 向量 (100, 0, 0);
// set polygon polygons[0] = CPolygon (0, 1, 2, 3);
// inform the polygon object that internal data changed polygonObject-> 消息 ( MSG_UPDATE ); } else { return maxon::UnexpectedError( MAXON_SOURCE_LOCATION ); }
The function RenderDocument() can be used to render a given BaseDocument .
// This example creates a BaseBitmap to render the given document using RenderDocument().// prepare bitmap AutoAlloc<BaseBitmap> bitmap; if (bitmap == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION ); const Int32 width = 1280; const Int32 height = 720; const IMAGERESULT imageRes = bitmap-> Init (width, height); if (imageRes != IMAGERESULT::OK ) return maxon::UnexpectedError( MAXON_SOURCE_LOCATION );
// define render settings RenderData * const rdata = doc->GetActiveRenderData(); if (rdata == nullptr ) return maxon::UnexpectedError( MAXON_SOURCE_LOCATION ); BaseContainer renderSettings = rdata-> GetData (); renderSettings. SetFloat ( RDATA_XRES , width); renderSettings. SetFloat ( RDATA_YRES , height);
// render the document const RENDERFLAGS flags = RENDERFLAGS::NODOCUMENTCLONE ; const RENDERRESULT res = RenderDocument (doc, renderSettings, nullptr , nullptr , bitmap, flags, nullptr ); if (res != RENDERRESULT::OK ) return maxon::UnknownError( MAXON_SOURCE_LOCATION );
// show result ShowBitmap (bitmap);
