Open Search
    Getting Started: 3D

    Overview

    Working with Documents

    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.

    See also

    // 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
    // make document the active document
    // set name
    newDoc->SetDocumentName("new_document.c4d");
    // update Cinema 4D
    void InsertBaseDocument(BaseDocument *doc)
    void SetActiveDocument(BaseDocument *doc)
    void EventAdd(EVENT eventflag=EVENT::NONE)
    Definition: c4d_basedocument.h:497
    void SetDocumentName(const Filename &fn)
    static BaseDocument * Alloc()
    #define MAXON_SOURCE_LOCATION
    Definition: memoryallocationbase.h:67

    Creating new Objects

    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.

    See also Scene Elements Overview.

    // This example creates a new "Cube" object and
    // inserts it into the given BaseDocument.
    // create a new cube object
    if (cube == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
    // insert object into the BaseDocument
    doc->InsertObject(cube, nullptr, nullptr);
    Definition: c4d_baseobject.h:248
    static BaseObject * Alloc(Int32 type)
    #define Ocube
    Cube.
    Definition: ge_prepass.h:1110
    const char * doc
    Definition: pyerrors.h:226

    Setting Parameters

    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).

    See 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 Vector size { 500, 500, 500 };
    void SetName(const maxon::String &name, Bool setDirty=true)
    Definition: c4d_baselist.h:2419
    Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
    Definition: lib_description.h:355
    Py_ssize_t size
    Definition: bytesobject.h:86
    #define ConstDescID(...)
    Definition: lib_description.h:594
    @ PRIM_CUBE_LEN
    Definition: ocube.h:6
    Represents a level within a DescID.
    Definition: lib_description.h:298

    Creating new Materials

    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. Material is the class representing the standard Cinema 4D material.

    See Materials and Shaders Overview.

    // This example creates a new material and a new shader for that material.
    // create a new material
    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 = ConstDescID(DescLevel(MATERIAL_COLOR_SHADER));
    material->SetParameter(shaderParameterID, noiseShader, DESCFLAGS_SET::NONE);
    void InsertShader(BaseShader *shader, BaseShader *pred=nullptr)
    Definition: c4d_baselist.h:2628
    Definition: c4d_basechannel.h:36
    static BaseShader * Alloc(Int32 type)
    Definition: c4d_basematerial.h:241
    static Material * Alloc()
    #define Xnoise
    Noise.
    Definition: ge_prepass.h:1349
    @ MATERIAL_COLOR_SHADER
    Definition: mmaterial.h:294

    Working with Tags

    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.

    See 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 = ConstDescID(DescLevel(TEXTURETAG_MATERIAL));
    textureTag->SetParameter(materialParameterID, material, DESCFLAGS_SET::NONE);
    // set projection
    const DescID projectionParameterID = ConstDescID(DescLevel(TEXTURETAG_PROJECTION));
    textureTag->SetParameter(projectionParameterID, TEXTURETAG_PROJECTION_UVW, DESCFLAGS_SET::NONE);
    void InsertTag(BaseTag *tp, BaseTag *pred=nullptr)
    Definition: c4d_basetag.h:50
    static BaseTag * Alloc(Int32 type)
    #define Ttexture
    Texture - TextureTag.
    Definition: ge_prepass.h:1401
    @ TEXTURETAG_MATERIAL
    Definition: ttexture.h:29
    @ TEXTURETAG_PROJECTION
    Definition: ttexture.h:10
    @ TEXTURETAG_PROJECTION_UVW
    Definition: ttexture.h:17

    Finding Elements in the Document

    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.

    See BaseDocument Manual.

    // 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();
    }
    const char const char * name
    Definition: abstract.h:195
    String GetName() const
    Definition: c4d_baselist.h:2412
    Definition: c4d_basematerial.h:28
    BaseMaterial * GetNext()
    Definition: c4d_basematerial.h:60
    BaseTag * GetFirstTag()
    Definition: c4d_baseobject.h:716
    BaseTag * GetNext()
    Definition: c4d_basetag.h:81
    Definition: c4d_string.h:39
    #define ApplicationOutput(formatString,...)
    Definition: debugdiagnostics.h:210

    Creating Polygon Objects

    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
    Vector* 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] = Vector(0, 0, 0);
    points[1] = Vector(0, 0, 100);
    points[2] = Vector(100, 0, 100);
    points[3] = Vector(100, 0, 0);
    // set polygon
    polygons[0] = CPolygon(0, 1, 2, 3);
    // inform the polygon object that internal data changed
    polygonObject->Message(MSG_UPDATE);
    }
    else
    {
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
    }
    Bool Message(Int32 type, void *data=nullptr)
    Definition: c4d_baselist.h:1458
    Vector * GetPointW()
    Definition: c4d_baseobject.h:1593
    Definition: c4d_baseobject.h:1765
    CPolygon * GetPolygonW()
    Definition: c4d_baseobject.h:1912
    static PolygonObject * Alloc(Int32 pcnt, Int32 vcnt)
    maxon::Vec3< maxon::Float64, 1 > Vector
    Definition: ge_math.h:145
    maxon::Bool Bool
    Definition: ge_sys_math.h:55
    maxon::Int32 Int32
    Definition: ge_sys_math.h:60
    #define MSG_UPDATE
    Must be sent if the bounding box has to be recalculated. (Otherwise use MSG_CHANGE....
    Definition: c4d_baselist.h:359
    Represents a polygon that can be either a triangle or a quadrangle.
    Definition: c4d_baseobject.h:44

    Rendering

    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
    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 RENDERRESULT res = RenderDocument(doc, renderSettings,
    nullptr, nullptr, bitmap, flags, nullptr);
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
    // show result
    ShowBitmap(bitmap);
    PyCompilerFlags * flags
    Definition: ast.h:14
    RENDERRESULT RenderDocument(BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)
    Bool ShowBitmap(const Filename &fn)
    Definition: ge_autoptr.h:37
    Definition: c4d_basecontainer.h:48
    void SetFloat(Int32 id, Float r)
    Definition: c4d_basecontainer.h:607
    BaseContainer GetData()
    Definition: c4d_baselist.h:2354
    Definition: c4d_basedocument.h:143
    Py_UCS4 * res
    Definition: unicodeobject.h:1113
    @ RDATA_XRES
    Definition: drendersettings.h:152
    @ RDATA_YRES
    Definition: drendersettings.h:153
    IMAGERESULT
    Definition: ge_prepass.h:3887
    @ OK
    Image loaded/created.
    RENDERFLAGS
    Definition: ge_prepass.h:4657
    @ NODOCUMENTCLONE
    Set to avoid an automatic clone of the scene sent to RenderDocument().
    RENDERRESULT
    Definition: ge_prepass.h:426
    @ OK
    Function was successful.
    unsigned long Py_ssize_t width
    Definition: pycore_traceback.h:88