Caption 1.0 User Manual

Abstract

[Demo image] Caption is a library module from the Persistence of Vision Ray Tracer (POV-Ray) Object Collection that creates boxes with imprinted text. With an opaque or partially transparent box, this is useful for quickly annotating busy scenes where text might otherwise be difficult to read.

Table of Contents

Overview

Downloaded Files

The italicized nnnnnn in some of the file names represents the 6-digit number that is in the name of the .zip file.

Key Files
File Description
caption.html The user manual (this document)
caption.inc The Caption software
caption.jpg Sample output
caption.pov A demonstration scene file
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
Other Files
File Description
caption.css A file used by the user manual
caption_description.txt A brief description of Caption
caption_keywords.txt A list of keywords
caption_prereqs.txt Prerequisites (empty file)
caption_prism.png Illustrations for the user manual
caption_thumbnail.jpg
cc-LGPL-a.png Administrative files
Versionnnnnnn.js

Table of contents

Prerequisites

Requires POV-Ray version 3.5 or later.

Namespace Compliance

All file names in this module and all global and local identifiers defined in caption.inc comply with the Object Collection naming standards, as revised August 2008 and proposed August 2012. The prefix for this module is “caption,” including any uppercase and lowercase variants; to avoid conflicts, do not declare identifiers that start with this prefix plus an underscore.

Usage

Include this file once prior to using any of the macros: 

#include "caption.inc"

Including the file more than once is harmless, though unnecessary.

Note that as of POV-Ray version 3.7, objects positioned with screen.inc do not contribute radiosity to a scene.

Table of contents

Macros

The Emission Argument

This argument controls the color of the caption objects independent of the environmental lighting. The effect is slightly different depending on the version of POV-Ray.

Caption (s_Text, s_Font, v_Padding, c_Text, c_Background, Emission)

Returns a box with text printed on its −z face. The −z face will lie in the x-y plane.

Arguments

s_Text:
The text string to be imprinted.
s_Font:
The font to be used. A null string defaults to Cyrvetic.
v_Padding:
A 3D vector. x and y are the padding to apply around the text; z is the depth of the box.
c_Object:
The color of the text.
c_Background:
The color of the negative space.
Emission:
See the description of the Emission argument.

Caption_Object (Object, v_Padding, c_Object, c_Background, Emission)

Returns a box with a cross section of an object imprinted on its −z face. The −z face will lie in the x-y plane. [Example of prismatic form] For predictable results, the object should be prismatic in form; that is, its cross section should not vary for any value of z.

Arguments

Object:
The object to be imprinted.
v_Padding:
A 3D vector. x and y are the padding to apply around the text; z is the depth of the box. The padding is measured around the object’s bounding box.
c_Object:
The color of the object to be imprinted.
c_Background:
The color of the negative space.
Emission:
See the description of the Emission argument.

Table of contents

Other Identifiers

Identifier Type Description Value
CAPTION_VERSION float The Caption version, in case the caller needs to know. 1.0

Internal Identifiers

Any identifiers in caption.inc that are not documented in this manual are considered “private” or “protected,” and are subject to change or elimination in a future update.

Table of contents

About Caption

Copyright © 2013 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Public License.

Change Log

Version Date Notes
N/A March 13, 2013
  • The software is created, based on code I wrote between 2004 and 2006.
1.0 December 23, 2013
  • A macro is added for general objects, not just text.
  • The software is adapted for the Object Collection.

Table of contents