Feedback Elements - Functions

• Concepts
• Common Feedback Element Properties
• Feedback Element Example

• Feedback Element Serials
  • sd-get-feedback-elem-new-serial-id

• Creation of Feedback Elements
  • sd-create-feedback-elem
  • sd-create-feedback-elem-pyramid
  • sd-create-feedback-elem-cut-pyramid
  • sd-create-feedback-elem-line
  • sd-create-feedback-elem-label

• Deletion of Feedback Elements
  • sd-delete-feedback-elem
  • sd-remove-from-feedback-elem

• Defaults for Feedback Elements
  • sd-set-feedback-elem-default-color
  • sd-set-feedback-elem-default-facets

• Modification of Feedback Elements
  • sd-set-feedback-elem-name
  • sd-show-feedback-elem
  • sd-hide-feedback-elem
  • sd-move-feedback-elem
  • sd-rotate-feedback-elem
  • sd-scale-feedback-elem
  • sd-set-feedback-elem-color
  • sd-set-feedback-elem-text

• Inquiries for Feedback Elements
  • sd-find-named-feedback-elem
  • sd-inq-feedback-elem-name
  • sd-inq-feedback-elem-serial
  • sd-inq-feedback-elem-color
  • sd-inq-feedback-elem-shape-id
  • sd-inq-feedback-elem-parent

SD-GET-FEEDBACK-ELEM-NEW-SERIAL-ID  [function]

(sd-get-feedback-elem-new-serial-id)

Description:

Generates a new serial and returns it's id.

Return Value:

number {FIXNUM} - The serial id

nil - failure

Example:

(setf my-serial (sd-get-feedback-elem-new-serial-id))

SD-CREATE-FEEDBACK-ELEM  [function]

(sd-create-feedback-elem :serial serial-id
                         :name   name
                         :vp     viewport
                         :color  color)

Description:

Creates an empty feedback element.

Parameters:

:serial {FIXNUM} - The id of a serial the element belongs to.

For color and facets the defaults of this serial are used if no other vales are specified during creation.

:name {STRING} - Optional parameter to specify the name of the feedback element.

Note: If given it has to be unique among all feedback elements.

:vp {STRING} - Name of the viewport to show the feedback element.

If no viewport is specified the feedback element will be displayed in all viewports.

:color {GPNT3D} - The color of the feedback element.

If not specified the default color of the serial is taken.

Return Value:

feedback element {HANDLE} - Handle of the feedback element

nil - failure

Example:

(setf feedback-element (sd-create-feedback-elem 
                          :serial my-serial
                          :name "ShowDistance"
                          :vp "vport1"
                          :color 1.0,0.0,0.0))

SD-CREATE-FEEDBACK-ELEM-PYRAMID  [function]

(sd-create-feedback-elem-pyramid start-pt
                                 end-pt
                                 width
                                 parent
                                 shape-id
                                 :facets num-facets
                                 :color color)

Description:

Creates a feedback element with a pyramid shape.

Parameters:

start-pt {POSITION3} - Top point of the pyramid.

end-pt {POSITION3} - Bottom center point of the pyramid.

width {DOUBLE} - Distance of the end-pt to the border points.

parent {HANDLE} - The parent feedback element.

shape-id {FIXNUM} - Id of the shape.

Has to be unique in the parent feedback element.

:facets {FIXNUM} - Optional parameter to specify the number of facets of the pyramid.

If not given the value from the parent feedback element is taken.

Note: The number of facets defines the number of sides of the pyramid. If this number gets higher depending on the size the pyramid looks like a cone.

:color {GPNT3D} - Optional parameter to specify the color of the pyramid.

If not given the color from the parent feedback element is taken.

Return Value:

feedback shape {HANDLE} - Handle of the feedback shape

nil - failure

Example:

(sd-create-feedback-elem-pyramid 0,0,0
                                 50,50,0
                                 6
                                 feedback-element
                                 1
                                 :facets 5)

SD-CREATE-FEEDBACK-ELEM-CUT-PYRAMID  [function]

(sd-create-feedback-elem-cut-pyramid start-pt
                                     end-pt
                                     start-width
                                     end-width
                                     parent
                                     shape-id
                                     :facets num-facets
                                     :color color)

Description:

Creates a feedback element with a cut pyramid shape.

Parameters:

start-pt {POSITION3} - Top point of the pyramid.

end-pt {POSITION3} - Bottom center point of the pyramid.

end-width {DOUBLE} - Distance of the end-pt to the bottom border points.

start-width {DOUBLE} - Distance of the start-pt to the top border points.

parent {HANDLE} - The parent feedback element.

shape-id {FIXNUM} - Id of the shape.

Has to be unique in the parent feedback element.

:facets {FIXNUM} - Optional parameter to specify the number of facets of the cut pyramid.

If not given the value from the parent feedback element is taken.

Note: The number of facets defines the number of sides of the pyramid frustum. If this number gets higher depending on the size, the pyramid frustum looks like a cone frustum. If in addition the end-width is equal to the start-width a cylinder shape is created.

:color {GPNT3D} - Optional parameter to specify the color of the cut pyramid.

If not given the color from the parent feedback element is taken.

Return Value:

feedback shape {HANDLE} - Handle of the feedback shape

nil - failure

Example:

(sd-create-feedback-elem-cut-pyramid 0,0,0
                                     50,50,0
                                     10
                                     20
                                     feedback-element
                                     2
                                     :facets 20)

SD-CREATE-FEEDBACK-ELEM-LINE  [function]

(sd-create-feedback-elem-line start-pt
                              end-pt
                              parent
                              shape-id
                              :color color)

Description:

Creates a feedback element with a line shape.

Parameters:

start-pt {POSITION3} - Start point of the line.

end-pt {POSITION3} - End point of the line.

parent {HANDLE} - parent feedback element.

shape-id {FIXNUM} - Id of the shape.

Has to be unique in the parent feedback element.

:color {GPNT3D} - Optional parameter to specify the color of the line.

If not given the color from the parent feedback element is taken.

Return Value:

feedback shape {HANDLE} - Handle of the feedback shape

nil - failure

Example:

(sd-create-feedback-elem-line 0,0,0
                              100,0,0
                              feedback-element
                              3
                              :color 0.0,1.0,0.5)

SD-CREATE-FEEDBACK-ELEM-LABEL  [function]

(sd-create-feedback-elem-label start-pt
                               direction
                               text-height
                               text
                               parent
                               shape-id
                               :color color)

Description:

Creates a feedback element with a text shape.

Parameters:

start-pt {POSITION3} - Start point of the label.

direction {VECTOR3} - Direction of the label.

text-height {DOUBLE} - Height of the label in mm.

text {STRING} - Text to be displayed in the label.

parent {HANDLE} - The parent feedback element.

shape-id {FIXNUM} - Id of the shape.

Has to be unique in the parent feedback element.

:color {GPNT3D} - Optional parameter to specify the color of the label.

If not given the color from the parent feedback element is taken.

Return Value:

feedback shape {HANDLE} - Handle of the feedback shape

nil - failure

Example:

(setf feedback-shape (sd-create-feedback-elem-label 10,10,10
                                                    1,0,0
                                                    50
                                                    "my label"
                                                    feedback-element
                                                    4
                                                    :color 1.0,1.0,0.0)

SD-DELETE-FEEDBACK-ELEM  [function]

(sd-delete-feedback-elem feedback-element)

Description:

Deletes a feedback element. All shapes of the feedback element will be deleted too.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to delete.

Return Value:

t - success

nil - failure

Example:

(sd-delete-feedback-elem feedback-element)

SD-REMOVE-FROM-FEEDBACK-ELEM  [function]

(sd-remove-from-feedback-elem feedback-element shape-id)

Description:

Deletes a single feedback shape from a feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the parent feedback element.

shape-id {FIXNUM} - Id of the shape to be removed.

Return Value:

t - success

nil - failure

Example:

(sd-remove-from-feedback-elem feedback-element 4)

SD-SET-FEEDBACK-ELEM-DEFAULT-COLOR  [function]

(sd-set-feedback-elem-default-color color
                                    :serial serial-id)

Description:

Sets the default color for the serial.

Parameters:

color {GPNT3D} - Default color for the serial.

:serial {FIXNUM} - serial id.

If not specified the default color of the basic feedback element serial is set.

Return Value:

t - success

nil - failure

Example:

(sd-set-feedback-elem-default-color 0.5,0.5,0.0 :serial my-serial)

SD-SET-FEEDBACK-ELEM-DEFAULT-FACETS  [function]

(sd-set-feedback-elem-default-facets facets
                                     :serial serial-id)

Description:

Sets the default number of facets for the serial.

Parameters:

facets {FIXNUM} - Default number of facets for the serial.

:serial {FIXNUM} - serial id.

If not specified the default number of facets of the basic feedback element serial is set.

Return Value:

t - success

nil - failure

Example:

(sd-set-feedback-elem-default-facets 20 :serial my-serial)

SD-SET-FEEDBACK-ELEM-NAME  [function]

(sd-set-feedback-elem-name feedback-element name)

Description:

Assigns a name to a feedback element or modifies the existing one.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to rename.

:name {STRING} - Name of the feedback element.

Has to be unique among all feedback elements.

Return Value:

t - success

nil - failure

Example:

(sd-set-feedback-elem-name feedback-element "NewName")

SD-SHOW-FEEDBACK-ELEM  [function]

(sd-show-feedback-elem feedback-element 
                       :vp view-port)

Description:

Shows a feedback element in one or all viewports.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to show.

:vp {STRING [nil]} - Name of the viewport to show the feedback element.

If no viewport is specified the feedback element will be displayed in all viewports.

Return Value:

t - success

nil - failure

Example:

(sd-show-feedback-elem feedback-element 
                       :vp "vport1")

SD-HIDE-FEEDBACK-ELEM  [function]

(sd-hide-feedback-elem feedback-element 
                       :vp view-port)

Description:

Hides a feedback element in one or all viewports.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to hide.

:vp {STRING [nil]} - Name of the viewport to hide the feedback element.

If no viewport is specified the feedback element will be hidden in all viewports.

Return Value:

t - success

nil - failure

Example:

(sd-hide-feedback-elem feedback-element 
                       :vp "vport1")

SD-MOVE-FEEDBACK-ELEM  [function]

(sd-move-feedback-elem feedback-element 
                       vector
                       :shape shape-id)

Description:

Moves either a feedback element along with all its shapes or a single shape of the feedback element specified by the shape id by a certain vector.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to modify.

vector {VECTOR3} - Vector to move the feedback element or feedback shape.

The feedback element or shape is moved in the direction specified by the vector along the length of the vector.

:shape {FIXNUM} - Shape-id of the shape to move.

If not specified the whole feedback element is moved.

Return Value:

t - success

nil - failure

Example:

(sd-move-feedback-elem feedback-element 20,20,0)

SD-ROTATE-FEEDBACK-ELEM  [function]

(sd-rotate-feedback-elem feedback-element 
                         from-direction
                         to-direction
                         rotation-center
                         :shape shape-id)

Description:

Rotates a feedback element from from-direction to to-direction around the rotation-center or applies the rotation to the feedback shape with the shape-id of the feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to modify.

from-direction {VECTOR3} - Start direction for the rotation.

to-direction {VECTOR3} - Destination direction for the rotation.

rotation-center {POSITION3} - Center point for the rotation.

:shape {FIXNUM} - Shape-id of the shape to rotate.

If not specified the whole feedback element is moved.

Return Value:

t - success

nil - failure

Example:

(sd-rotate-feedback-elem feedback-element 
                         1,0,0
                         0,1,0
                         0,0,0)

SD-SCALE-FEEDBACK-ELEM  [function]

(sd-scale-feedback-elem feedback-element 
                        scale-factor
                        scale-center
                        :shape shape-id)

Description:

Scales either a feedback element along with all its shapes or a single shape of the feedback element specified by the shape id around the scale-center by the given scale-factor.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to modify.

scale-factor {DOUBLE} - Factor for scaling.

scale-center {POSITION3} - Center for scaling.

:shape {FIXNUM} - Shape-id of the shape to scale.

If not specified the whole feedback element is scaled.

Return Value:

t - success

nil - failure

Example:

(sd-scale-feedback-elem feedback-element 3 0,0,0 :shape 2)

SD-SET-FEEDBACK-ELEM-COLOR  [function]

(sd-set-feedback-elem-color feedback-element 
                            color
                            :shape shape-id)

Description:

Sets the color of a feedback element or the color of a single feedback shape with the shape-id.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to modify.

color {GPNT3D} - The color to set.

:shape {FIXNUM} - Shape-id of the shape to change the color.

If not specified the color of the whole feedback element is changed.

Return Value:

t - success

nil - failure

Example:

(sd-set-feedback-elem-color feedback-element 
                            0.5,0.5,0.0
                            :shape 3)

SD-SET-FEEDBACK-ELEM-TEXT  [function]

(sd-set-feedback-elem-text feedback-element 
                           text-height
                           text
                           shape-id)

Description:

Changes the text height and the text for a label feedback shape with the given shape-id in the feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to modify.

text-height {DOUBLE} - Height of the label text.

text {STRING} - Text for the label.

shape-id {FIXNUM} - Shape-id of the shape.

Return Value:

t - success

nil - failure

Example:

(sd-set-feedback-elem-text feedback-element 
                           30
                           "my new label text"
                           4)

SD-FIND-NAMED-FEEDBACK-ELEM  [function]

(sd-find-named-feedback-elem name)

Description:

Searches a feedback element with the given name.

Parameters:

name {STRING} - Name of a feedback element.

Return Value:

feedback element {HANDLE} - Handle of the feedback element.

nil - failure

Example:

(setf feedback-element (sd-find-named-feedback-elem "NewName"))

SD-INQ-FEEDBACK-ELEM-NAME  [function]

(sd-inq-feedback-elem-name feedback-element)

Description:

Inquires the name of a feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to inquire.

Return Value:

name {STRING} - Name of the feedback element.

nil - The feedback element has no name.

Example:

(setf name (sd-inq-feedback-elem-name feedback-element))

SD-INQ-FEEDBACK-ELEM-SERIAL  [function]

(sd-inq-feedback-elem-serial feedback-element)

Description:

Inquires the serial id of a feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to inquire.

Return Value:

serial {FIXNUM} - Serial-id of the feedback element.

nil - feedback element has no serial id.

Example:

(setf serial (sd-inq-feedback-elem-serial feedback-element))

SD-INQ-FEEDBACK-ELEM-COLOR  [function]

(sd-inq-feedback-elem-color feedback-element 
                            :shape shape-id)

Description:

Inquires the color of a feedback element or the color of the feedback shape with shape-id of the given feedback element.

Parameters:

feedback-element {HANDLE} - Handle of the feedback element to inquire.

:shape {FIXNUM} - Shape-id of the shape.

Return Value:

color {GPNT3D} - Color of the feedback element or feedback shape.

nil - failure

Example:

(setf color (sd-inq-feedback-elem-color feedback-element))

SD-INQ-FEEDBACK-ELEM-SHAPE-ID  [function]

(sd-inq-feedback-elem-shape-id feedback-shape)

Description:

Inquires the shape-id of a feedback shape.

Parameters:

feedback-shape {HANDLE} - Handle to a feedback shape.

Return Value:

shape-id {FIXNUM} - Shape-id of the feedback-shape.

nil - failure.

Example:

(setf shape-id (sd-inq-feedback-elem-shape-id feedback-shape))

SD-INQ-FEEDBACK-ELEM-PARENT  [function]

(sd-inq-feedback-elem-parent feedback-shape)

Description:

Inquires the parent of a feedback shape.

Parameters:

feedback-shape {HANDLE} - Handle of a feedback shape.

Return Value:

feedback element {HANDLE} - Handle of the parent feedback element.

nil - failure

Example:

(setf parent (sd-inq-feedback-elem-parent feedback-shape))