BlenderImport(3pm)

💖 BlenderImport — the manual, but make it make sense 💖

okay bestie, gather round, because this is BlenderImport(3pm) from the User Contributed Perl Documentation and it's literally the little module that lets your Perl scripts eat Blender files. no cap.

---

✨ NAME ✨

XRacer::BlenderImport — it imports the files that xracer-blenderexport.py spits out. that's the whole job. iconic.

---

🌸 SYNOPSIS 🌸

  use XRacer::BlenderImport;

  $world = parse XRacer::BlenderImport [ $filename ];

  $index = $world->add_vertex ($vertex);
  $verticesref = $world->get_vertices;
  %layerinfo = $world->get_layer_info;

  @objects = $world->get_meshes_in_layer ($layer);

look at her go 🫶

---

🦋 DESCRIPTION 🦋

so the XRacer::BlenderImport module is packing functions that pull special XRacer-specific Blender files into your Perl scripts. and where did those Blender files come from? the xracer-blenderexport.py Python script for Blender exported them earlier, bestie. it's a whole pipeline. 💅

what XRacer::BlenderImport does is parse the blender.export file, clean it up (removing multiple vertices, for example — yes, it's tidying up after everybody, main character energy fr), and hand you an internal world representation. the world is split into layers (which correspond to the layers in the original Blender image), and inside each of those layers lives a set of meshes. cute, organised, slay.

🎀 FUNDAMENTAL TYPES 🎀

okay so vertices? they live in one big global list, so that shared vertices only get stored once instead of a hundred times. efficiency queen. a vertex structure looks exactly like this:

  $vertex = { coords => [ $x, $y, $z, 0 ],
              texcoords => [ $u, $v ],
              normal => [ $nx, $ny, $nz, 0 ],
              colour => [ $r, $g, $b, $a ] };

the fields, in order, are: the coordinates of the vertex, the texture coordinates, the normal vector at this point, and the colour of the vertex. four little bundles of joy. 💖

faces are stored simply as a list of vertex indices (relative to that global list of vertices we just talked about). a face looks like this:

  $face = { vertices => [ $index0, $index1, $index2, ... ] }

and heads up: faces have at least three vertices, and maybe more. no degenerate two-point nonsense around here. 💀

a mesh is a list of faces plus extra info, like the name of the mesh (the object). a mesh structure looks like this:

  $mesh = { name => $name,
            layer => $layer,
            faces => \@faces,
            material => [ $red, $green, $blue ],
            has_colours => $has_colours,
            has_texcoords => $has_texcoords,
            has_material => $has_material };

the fields are: the name of the mesh (or object), the layer the object exists on, the list of faces, the material, and then three flags that Blender passes to us: did the user supply vertex colours? did the user supply texture coordinates? and did the user supply a material? three little yes/no besties. ⭐

---

👑 CLASS METHODS 👑

• $world = parse XRacer::BlenderImport [ $filename ]; — parses the import file $filename (or blender.export if you didn't give it a filename, she'll assume) and generates a world representation. and if the file could not be parsed? she prints an error message and returns undef. so like, check for that, bestie. 🙈

---

💜 OBJECT METHODS 💜

• $index = $world->add_vertex ($vertex) — adds a single vertex to the world object (remember, vertices live in one big shared list so common vertices get folded into one). returns the vertex index of the new vertex. and here's the cute part: if another vertex already existed with the same position, texture coordinates, normal and colour, then this function returns the index of that other vertex instead of making a whole fresh vertex object. recycling! we love her. 🌈
• $verticesref = $world->get_vertices — hands you back a reference to the global list of vertices. and listen: you must not update or change this list. do not touch. use the add_vertex method instead, okay? hands off the merch. 😭
• %layerinfo = $world->get_layer_info — returns a hash. the keys are layers that contain at least one object. the values are how many objects are in that layer. for example, if the world had 3 objects on layer 1, 1 object on layer 2 and 4 objects on layer 5, the hash you'd get back would be equivalent to:

  %layerinfo = ( 1 => 3, 2 => 1, 5 => 4 );

literally just a headcount per layer. adorable.

• @objects = $world->get_meshes_in_layer ($layer) — gives you the list of objects (i.e. meshes) found in layer $layer. and if you wanna know what a mesh structure looks like, scroll up to the DESCRIPTION section, it's all there. iykyk. 🎀

---

🌟 AUTHOR 🌟

Richard W.M. Jones, <rich@annexia.org>

the man, the myth, the legend. 💅

---

🫶 COPYRIGHT 🫶

XRacer is copyright (C) 1999-2000 Richard W.M. Jones (rich@annexia.org) and other contributors listed in the AUTHORS file.

---

🔥 SEE ALSO 🔥

perl(1), xracer(6).

go read those too, bestie, they're right there.

---

and that's the whole page, periodt. 💖 this gorgeous thing was perl v5.40.0, dated 2025-01-25, and it goes by BlenderImport(3pm). mwah, stan her, bye! ✨🎀🦋